> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.

# Address book
Source: https://docs.goshippo.com/address-api/address-book

Store, retrieve, update, and delete addresses using the Shippo Addresses API address book.

An address book is a digital store for addresses. It stores addresses and helps you update, retrieve, and delete addresses. Using the Addresses API means you do not need to create your own storage solution for this common challenge.
Using an address book is also a great way to improve the customer checkout experience. Enabling your customers to save their addresses during checkout simplifies future purchases with your business.

<Info>
  **Note**

  Address object IDs cannot be used with previous versions of the Shippo API. There is a limit of 3,000 addresses that can be stored.
</Info>

## Create an address book entry

To store an address for later use in the Addresses API, follow this example. Note, you cannot save identical addresses.

<CodeGroup>
  ```json cURL theme={null}
  curl -i -X POST \
    https://api.goshippo.com/v2/addresses \
    -H 'Authorization: ShippoToken <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "Wilson",
      "organization": "Shippo",
      "email": "user@shippo.com",
      "phone": "+1-4155550132",
      "address_line_1": "731 Market Street",
      "address_line_2": "#200",
      "city_locality": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103",
      "country_code": "US",
      "address_type": "residential"
    }'
  ```

  ```json Create address response theme={null}
  {
          "id": "7cf70f716ad0459cbd0de8652689192b",
          "address": {
          "name": "Wilson",
          "email": "user@shippo.com",
          "phone": "+1-4155550132",
          "organization": "Shippo",
          "address_line_1": "731 Market Street",
          "address_line_2": "#200",
          "city_locality": "San Francisco",
          "state_province": "CA",
          "postal_code": "94103",
          "country_code": "US",
          "address_type": "residential"
  },
      "updated_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
  }
  ```
</CodeGroup>

## Retrieve addresses

You can retrieve an address using an address object ID. If you don't know the object ID for an address, see the example to retrieve multiple addresses.
To retrieve a single address using an object ID, follow this example.

<CodeGroup>
  ```json cURL theme={null}
  curl -i -X GET \
    'https://api.goshippo.com/v2/addresses/{address_id}' \
    -H 'Authorization: ShippoToken <API_TOKEN>'
  ```

  ```json Retrieve single address response theme={null}
  {
    "id": "5029d2e1d0994bd0a8efd7d12485539d",
    "address": {
    "name": "Wilson",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "organization": "Shippo",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  },
    "updated_at": "2023-11-16T10:13:59.887946Z",
    "created_at": "2023-11-16T10:13:59.887946Z"
  }
  ```
</CodeGroup>

To retrieve multiple addresses with a single call, follow this example.
You can reduce the number of returned results using the following parameters.

| Parameter | Description                                                                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`   | Limits the number of returned addresses. For example, if 20 records match your query and `limit` is set to 5, only the first 5 addresses are returned          |
| `offset`  | The number of addresses to skip in the result set. For example, if 100 addresses match your query, if you offset 50 and limit 20, then you get addresses 50-70 |
| `search`  | Only addresses that contains this string anywhere in the address will be returned                                                                              |

<CodeGroup>
  ```json cURL theme={null}
  curl -i -X GET \
    'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string' \
    -H 'Authorization: ShippoToken <API_TOKEN>'
  ```

  ```json Retrieve multiple addresses response theme={null}
  {
    "offset": 0,
    "limit": 30,
    "count": 3,
    "results": [
      {
        "id": "5029d2e1d0994bd0a8efd7d12485539d",
        "address": {
          "name": "Wilson",
          "email": "user@shippo.com",
          "phone": "+1-4155550132",
          "organization": "Shippo",
          "address_line_1": "731 Market Street",
          "address_line_2": "#200",
          "city_locality": "San Francisco",
          "state_province": "CA",
          "postal_code": "94103",
          "country_code": "US",
          "address_type": "residential"
        },
        "updated_at": "2023-11-16T10:13:59.887946Z",
        "created_at": "2023-11-16T10:13:59.887946Z"
      },
      {
        "id": "45472328338149bda583cd6abec7fd75",
        "address": {
          "name": "Wilson 2",
          "email": "user@shippo.com",
          "phone": "+1-4155550132",
          "organization": "Shippo",
          "address_line_1": "731 Market Street",
          "address_line_2": "#200",
          "city_locality": "San Francisco",
          "state_province": "CA",
          "postal_code": "94103",
          "country_code": "US",
          "address_type": "residential"
        },
        "updated_at": "2023-11-17T16:26:53.951934Z",
        "created_at": "2023-11-17T16:26:53.951934Z"
      },
      {
        "id": "81c1dc22258344dea6a78565797ffd44",
        "address": {
          "name": "Wilson 2",
          "email": "user@shippo.com",
          "phone": "+1-4155550132",
          "organization": "Shippo 2",
          "address_line_1": "731 Market Street",
          "address_line_2": "#200",
          "city_locality": "San Francisco",
          "state_province": "CA",
          "postal_code": "94103",
          "country_code": "US",
          "address_type": "residential"
        },
        "updated_at": "2023-11-17T16:27:13.130576Z",
        "created_at": "2023-11-17T16:27:13.130576Z"
      }
    ]
  }
  ```
</CodeGroup>

## Update an address

To update an existing address, follow this example.

```json cURL theme={null}
curl -i -X PUT \
  'https://api.goshippo.com/v2/addresses/{address_id}' \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Wilson",
    "organization": "Shippo",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  }'
```

## Delete addresses

To delete an address that you have created, follow this example.

```json cURL theme={null}
curl -i -X DELETE \
  'https://api.goshippo.com/v2/addresses/{address_id}' \
  -H 'Authorization: ShippoToken <API_TOKEN>'
```


# Addresses API introduction
Source: https://docs.goshippo.com/address-api/address-intro

Get started with the Shippo Addresses API for storing, validating, and parsing addresses in your application.

The Shippo Addresses API is a suite of dedicated tools for managing addresses in your application.

Some applications of the Addresses API include the following.

* Storing, managing, and retrieving addresses.
* Checking addresses to ensure they are valid.
* Parsing and importing an address from a string.

***

Before you begin, examples in this guide assume you have a [Shippo API token](/guides/authentication). In the code examples, when you see `<API_TOKEN>`, replace it with your own token.

When testing and learning, we recommend using a [test token](/guides/testing).


# Address parser
Source: https://docs.goshippo.com/address-api/address-parser

Convert an address string into a structured address object using the Shippo Addresses API parser.

A parser is a tool for analyzing a string with some predefined rules. Using the Addresses API parser, you can convert a string into a correctly formatted address object.

The parser expects an address string in the following formats.

* For best results, use a comma `,`  as a delimiter.
* Your address must follow this order: `address_line_1`, `address_line_2`, `city_locality`, `state_province`, `postal_code`, `country_code`.
* `phone` and `email` can be in any part of the string.

<CodeGroup>
  ```string Good string example ✅ theme={null}
  11605 W Belleview Ave, Littleton, Colorado, 80127, US
  ```

  ```string Bad string example ❌ theme={null}
  Colorado 11605 W Belleview Ave Littleton 80127 US
  ```
</CodeGroup>

## Parse a string

Follow this example to parse a string to an address object.

<CodeGroup>
  ```json cURL theme={null}
  curl -i -X GET \
    'https://api.goshippo.com/v2/addresses/parse?address=Shippo%20731%20Market%20St%20%23200%2C%20San%20Francisco%2C%20CA%2094103%20US%20shippo%40shippo.com%20%2B1-555-999-8888' \
    -H 'Authorization: ShippoToken <API_TOKEN>'
  ```

  ```json Response theme={null}
  {
      "email": "shippo@shippo.com",
      "phone": "+1-555-999-8888",
      "address_line_1": "731 MARKET ST",
      "address_line_2": "#200",
      "city_locality": "SAN FRANCISCO",
      "state_province": "CA",
      "postal_code": "94103",
      "country_code": "US"
  }
  ```
</CodeGroup>

## Try Address Parser

Use this demo to learn about the Shippo Address Parser. This demo takes an address as an input, and then displays the response from the Address Parser method as visualized content and as a JSON object.

<AddressParserDemo />


# Address validation
Source: https://docs.goshippo.com/address-api/address-validate

Validate shipping addresses with the Shippo API to prevent failed deliveries and correction surcharges.

Address validation is a service that tests your address to check if it is valid.
By checking for invalid addresses and instantly correcting them to ensure accurate addresses, this helps prevent failed deliveries and address correction surcharges and allows you to protect your bottom line.
You can have customers validate addresses through the Addresses API during checkout or you can validate addresses while you are creating labels.

The returned results include a `validation_result` that indicates if the address is valid. If the validation identifies changes needed in order to make your address valid, the API response recommends a new address in `recommended_address`.

## Using address validation

If you are interested in using Shippo’s Address Validation API or have any questions about pricing, please [contact our sales team](https://goshippo.com/contact/sales).

## Validate an address

To validate an address, follow this example.

```json cURL theme={null}
curl -i -X GET \
  'https://api.goshippo.com/v2/addresses/validate?address_line_1=320J Outerbelt Street&city_locality=Columbus&state_province=OH&postal_code=43213&country_code=US&organization=Shippo' \
  -H 'Authorization: ShippoToken <API_TOKEN>'
```

```json Validate address response theme={null}
{
    "original_address": {
        "address_line_1": "320J Outerbelt Street",
        "city_locality": "Columbus",
        "state_province": "OH",
        "postal_code": "43213",
        "country_code": "US",
        "organization": "Shippo"
    },
    "recommended_address": {
        "address_line_1": "320 Outerbelt St",
        "address_line_2": "Ste J",
        "city_locality": "Columbus",
        "state_province": "OH",
        "postal_code": "43213",
        "country_code": "US",
        "organization": "Shippo",
        "complete_address": "Shippo; 320 Outerbelt St Ste J; Columbus OH 43213-1537; US",
        "confidence_result": {
            "score": "high",
            "code": "postal_data_match",
            "description": "The address has been completely verified to the most granular level possible."
        }
    },
    "analysis": {
        "validation_result": {
            "value": "partially_valid",
            "reasons": [
                {
                    "code": "address_abbreviation_fixed",
                    "description": "Address inputted was standardized for abbreviations according to postal authority rules."
                }
            ]
        },
        "address_type": "commercial",
        "changed_attributes": [
            "address_line_2",
            "address_line_1"
        ]
    },
    "geo": {
        "latitude": 39.98725,
        "longitude": -82.83042
    }
}
```

<br />

## Try address validation

Try our Address Validation API using any example address from the dropdown below. You can find the breakdown of the address validation result, and the raw API response as a JSON object.

<AddressValidationDemo />

## Migrate address validation

If you use the [legacy Shippo validation](/addresses/address-validation), you may choose to update your integration to use the latest Addresses API. Use this guide to understand what has changed and what you need to do to use the latest version.

The legacy address validation supported two methods for address validation.

1. When [creating a new address object](/addresses/address-validation#how-to-validate-addresses) using the `validate` option.
2. Validating [existing Address objects](/addresses/address-validation#validate-existing-address-objects).

The latest Address API validation does not support validating addresses using the object ID of an address.

The changes are as follows.

<img alt="step 1 icon" /> Address fields are passed as query parameters instead of fields in the body of the request.

```shell Address V2 validation theme={null}
curl -i -X GET \
  'https://api.goshippo.com/v2/addresses/validate?address_line_1=215 Clayton St&city_locality=San Francisco&state_province=CA&postal_code=94117&country_code=US&organization=Shippo' \
  -H 'Authorization: ShippoToken <API_TOKEN>'
```

```shell legacy Address validation theme={null}
curl -i https://api.goshippo.com/addresses/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d company="Shippo"\
    -d street1="215 Clayton St."\
    -d city="San Francisco"\
    -d state="CA"\
    -d zip=94117\
    -d country="US"\
    -d validate=true
```

<img alt="step 2 icon" /> The path must be prefixed with `/v2`.

```shell Address V2 theme={null}
https://api.goshippo.com/v2/addresses/

```

```shell legacy Address theme={null}
https://api.goshippo.com/addresses/
```

<img alt="step 3 icon" /> The returned response includes a richer details about the validated address including the following.

* A `recommended_address`.
* A `confidence_result` with a `score` and `description` describing the quality of the recommended address.
* `analysis` that includes details about the validation.
* `changed_attributes` that lists which values changed between the `original_address` and the `recommended_address`.

```json Address V2 response theme={null}
{
  "original_address": {
    "address_line_1": "965 Mission St # 572",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103-2921",
    "country_code": "US",
    "name": "Mr. Hippo"
  },
  "analysis": {
    "validation_result": {
      "value": "valid",
      "reasons": [
        {
          "code": "address_found",
          "description": "The entire address is present in the database."
        }
      ]
    },
    "address_type": "commercial"
  },
  "geo": {
    "latitude": 37.78152,
    "longitude": -122.40786
  }
}
```

```json legacy Address response theme={null}
{
    "object_created": "2024-02-15T16:04:06.649Z",
    "object_updated": "2024-02-15T16:04:06.674Z",
    "object_id": "3af6fd3321c3468caeb5cf6d5545de36",
    "is_complete": true,
    "validation_results": {
        "is_valid": true,
        "messages": [
            {
                "source": "Shippo Address Validator",
                "code": "Default Match",
                "type": "address_warning",
                "text": "More information, such as an apartment or suite number, may give a more specific address."
            }
        ]
    },
    "object_owner": "adrian.collins@goshippo.com",
    "name": "Mr Hippo",
    "company": "",
    "street_no": "",
    "street1": "965 Mission St # 572",
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103-2921",
    "country": "US",
    "longitude": -122.40786,
    "latitude": 37.78152,
    "phone": "4151234567",
    "email": "mrhippo@goshippo.com",
    "is_residential": false,
    "metadata": "",
    "test": true
}
```

<img alt="step 4 icon" /> The returned address is not stored.

<img alt="step 5 icon" /> The following fields have changed.

| V1 Address Field            | V2 Address Field | Notes                          |
| --------------------------- | ---------------- | ------------------------------ |
| \*\* Deprecated Fields \*\* |                  |                                |
| is\_complete                |                  |                                |
| object\_created             |                  |                                |
| object\_updated             |                  |                                |
| object\_id                  |                  |                                |
| object\_owner               |                  |                                |
| street\_no                  |                  |                                |
| street3                     |                  |                                |
| phone                       |                  |                                |
| email                       |                  |                                |
| test                        |                  |                                |
| validation\_results         |                  | Moved to analysis but modified |
| metadata                    |                  |                                |

| V1 Address Field                                            | V2 Address Field | Notes |
| ----------------------------------------------------------- | ---------------- | ----- |
| \*\* original\_address \*\*, \*\* recommended\_address \*\* |                  |       |
| name                                                        | name             |       |
| company                                                     | organization     |       |
| street1                                                     | address\_line\_1 |       |
| street2                                                     | address\_line\_2 |       |
| city                                                        | city\_locality   |       |
| state                                                       | state\_province  |       |
| zip                                                         | postal\_code     |       |
| country                                                     | country\_code    |       |

| V1 Address Field                                                                                        | V2 Address Field   | Notes                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \*\* recommended\_address (exclusive fields) \*\*                                                       |                    |                                                                                                                                                                                                                                   |
| \*\* recommended\_address is present if we believe there is a more accurate version of the address \*\* |                    |                                                                                                                                                                                                                                   |
|                                                                                                         | complete\_address  | The full address in one string whenever available                                                                                                                                                                                 |
|                                                                                                         | confidence\_result | Contains the score field which takes values of high, medium, low; contains the code field which is the machine readable explanation to the score; and the description field which is the human friendly explanation to the score. |

| V1 Address Field              | V2 Address Field            | Notes                                                                                                                                                                                                                                  |
| ----------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \*\* analysis \*\*            |                             |                                                                                                                                                                                                                                        |
| is\_residential               | address\_type               | changed from boolean to an enum. `residential`, `commercial`, `unknown`, `po_box`, `military`                                                                                                                                          |
| validation\_results           | validation\_results         | changed from boolean to an object.                                                                                                                                                                                                     |
| validation\_results.is\_valid | validation\_results.value   | Changed from Bool to enum.  `valid`, `partially_valid`, `invalid`                                                                                                                                                                      |
| validation\_results.messages  | validation\_results.reasons | Each reason is an object containing the code and the description. The code is the machine readable explanation to why the address is valid, partially valid, or invalid. And the description is the human friendly value for the same. |
|                               | changed\_attributes         | list of fields changed in the recommended address from the original address.                                                                                                                                                           |

| V1 Address Field | V2 Address Field | Notes |
| ---------------- | ---------------- | ----- |
| \*\* geo \*\*    |                  |       |
|                  | latitude         |       |
|                  | longitude        |       |


# Address validation
Source: https://docs.goshippo.com/addresses/address-validation

Validate addresses before creating labels using the Shippo API to avoid failed deliveries and surcharges.

To prevent failed deliveries and address correction surcharges, validate your addresses through our API before you create labels.

## Address validation logic

The Shippo address validation method verifies an Address by checking whether we have a matching verified deliverable address. The following results are possible:

* **Address is valid**: The source address is valid and unique. The API will return a new, cleaned address object with the `validation_results` object's field `is_valid` is set to `true`.
* **Address is invalid**: The address validator has processed the address, but could not find a match. There are three possible reasons: (1) the address doesn't exist, (2) the address isn't deliverable, or (3) the address is too ambiguous. The API will return a new address object with the `validation_results` object's `is_valid` field set to `false`. The API also returns messages indicating why the validation failed.

It is also worth noting that if the address object you created is missing information necessary for creating a shipment, the `is_complete` field will be `false`.

The address validator also returns whether the address is residential or commercial via the `is_residential` flag. If the residential/commercial type could not be determined, the value will be null.

## How to validate addresses

Validating addresses is easy. In your Address POST request, add a field `validate` set to `true`:

**Request:**

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/addresses/\
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -d name="Shawn Ippotle"\
      -d company="Shippo"\
      -d street1="215 Clayton St."\
      -d city="San Francisco"\
      -d state="CA"\
      -d zip=94117\
      -d country="US"\
      -d email="shippotle@shippo.com"\
      -d validate=true
  ```

  ```python Python theme={null}
  shippo_sdk.addresses.create(
      components.AddressCreateRequest(
          name="Shawn Ippotle",
          company="Shippo",
          street1="215 Clayton St.",
          city="San Francisco",
          state="CA",
          zip="94117",
          country="US",
          email="shippotle@shippo.com",
          validate = True
      )
  )
  ```

  ```php PHP theme={null}
  $fromAddress = Shippo_Address::create( array(
      "name" => "Shawn Ippotle",
      "company" => "Shippo",
      "street1" => "215 Clayton St.",
      "city" => "San Francisco",
      "state" => "CA",
      "zip" => "94117",
      "country" => "US",
      "email" => "shippotle@shippo.com",
      "validate" => true
  ));
  ```

  ```typescript TypeScript theme={null}
  const address = await shippo.addresses.create({
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      email: "shippotle@shippo.com",
      validate: true
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> addressMap = new HashMap<String, Object>();
  addressMap.put("name", "Mr. Hippo");
  addressMap.put("company", "Shippo");
  addressMap.put("street1", "215 Clayton St.");
  addressMap.put("city", "San Francisco");
  addressMap.put("state", "CA");
  addressMap.put("zip", "94117");
  addressMap.put("country", "US");
  addressMap.put("phone", "+1 555 341 9393");
  addressMap.put("email", "support@goshipppo.com");
  addressMap.put("validate", "true");

  Address createAddress = Address.create(addressMap);
  ```

  ```csharp C# theme={null}
  Address address = await sdk.Addresses.CreateAsync(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Company = "Shippo",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Email = "shippotle@shippo.com",
          Validate = true,
      }
  );
  ```
</CodeGroup>

You will get a response in the following format:

**Response:**

```json theme={null}
{
    "object_created": "2015-03-30T23:47:11.574Z",
    "object_updated": "2015-03-30T23:47:11.596Z",
    "object_id": "67183b2e81e9421f894bfbcdc4236b16",
    "is_complete": false,
    "validation_results": {
        "is_valid": false,
        "messages": [
            {
                "source": "USPS",
                "code": "Address Not Found",
                "type": "address_error",
                "text": "The address as submitted could not be found. Please check for excessive abbreviations in the street address line or in the City name."
            }
        ]
    },
    "object_owner": "shippotle@shippo.com",
    "name": "Shawn Ippotle",
    "company": "Shippo",
    "street_no": "",
    "street1": "215 HIPPO ST.",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94107",
    "country": "US",
    "phone": "",
}
```

## Validate existing Address objects

To validate existing addresses, simply make a GET request to the validate endpoint at

```
https://api.goshippo.com/addresses/<address-object-id>/validate/

```

For example:

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/\
      -H "Authorization: ShippoToken <API_TOKEN>"
  ```

  ```python Python theme={null}
  shippo_sdk.addresses.validate('d799c2679e644279b59fe661ac8fa488')
  ```

  ```php PHP theme={null}
  Shippo_Address::validate('d799c2679e644279b59fe661ac8fa488');
  ```

  ```typescript TypeScript theme={null}
  shippo.addresses.validate("d799c2679e644279b59fe661ac8fa488")
  ```

  ```java Java theme={null}
  Address.validate("d799c2679e644279b59fe661ac8fa488");
  ```

  ```csharp C# theme={null}
  await sdk.Addresses.ValidateAsync("d799c2679e644279b59fe661ac8fa488");
  ```
</CodeGroup>

This call returns the same response JSON as the sample response above.

***

## Global address validation

The way to validate global addresses (non-U.S.) would operate the same as U.S. addresses. The key difference that you'll notice is in the response that you get back. Global address validation has additional messages for specifying the precision of the address that is returned (i.e. street level, neighborhood level, state level, rooftop level, etc.).

If you attempt to validate a non-U.S. address using your Test API token, we will simply pass back the address information without performing any validation. Please be aware that if you simply switch from using your Test token to using your Live token, you *will* incur charges for using your Live token for validating Global addresses.

**Response:**

```json theme={null}
{
    "object_created": "2017-07-26T17:52:37.305Z",
    "object_updated": "2017-07-26T17:52:37.351Z",
    "object_id": "b7f9709df3914d1ca6efe4c30e7b0572",
    "is_complete": true,
    "validation_results": {
        "is_valid": true,
        "messages": [
            {
                "source": "Shippo Address Validator",
                "type": "address_correction",
                "code": "administrative_area_change",
                "text": "The administrative area (state or province) was added or changed."
            },
            {
                "source": "Shippo Address Validator",
                "code": "geocoded_rooftop",
                "text": "The record was geocoded down to rooftop level, meaning the point is within the property boundaries (most often the center)."
            },
            {
                "source": "Shippo Address Validator",
                "code": "premises_full",
                "text": "The address has been verified to the Premise (House or Building) Level, which is the highest level possible with the reference data."
            }
        ]
    },
    "object_owner": "hippo@shippo.com",
    "name": "Hippo Shippo",
    "company": "Shippo",
    "street_no": "2",
    "street1": "Unter den Linden",
    "street2": "",
    "street3": "",
    "city": "Berlin",
    "state": "",
    "zip": "10117",
    "country": "DE",
    "longitude": "13.39751",
    "latitude": "52.51785",
    "phone": "14151234567",
    "email": "hippo@shippo.com",
    "is_residential": null,
    "metadata": "",
    "test": false
}
```

### Messages

The messaging structure for global addresses will give details about what was changed and the specificity of your results. You will find these messages in the `messages` field which is an array comprised of all messages returned in processing your address validation request.

* **type**: this field contains a token that you can use for understanding the type of message that was created. Below is a comprehensive list of the message types that can be returned:
  * address\_error
  * address\_warning
  * address\_correction
  * geocode\_level
  * geocode\_error
  * service\_error
* **code**: the code further specifies the type of warning, error or message. Some examples are:
  * administrative\_area\_change
  * geocoded\_rooftop
  * premises\_full
* **text**: this field contains a text description of the message. Below are some examples of the text that will accompany the above message codes.
  * *The address could not be verified at least up to the postal code level.*
  * *Street could not be matched to a unique street name. Please add more details to the street name.*
  * *The address matched multiple records, please enter more information to locate a unique address.*
* **source**: this field describes where the message is coming from, which is always set to"Shippo Address Validator".

```json theme={null}
{
  ...
  "is_complete": true,
  "validation_results": {
    "is_valid": true,
    "messages": [
      {
        "source": "Shippo Address Validator",
        "type": "address_correction",
        "code": "administrative_area_change",
        "text": "The administrative area (state or province) was added or changed."
      },
      {
        "source": "Shippo Address Validator",
        "type": "geocode_level",
        "code": "geocoded_rooftop",
        "text": "The record was geocoded down to rooftop level, meaning the point is within the property boundaries (most often the center)."
      },
      {
        "source": "Shippo Address Validator",
        "type": "address_warning",
        "code": "premises_full",
        "text": "The address has been verified to the Premise (House or Building) Level, which is the highest level possible with the reference data."
      }
    ]
  },
  "object_owner": "hippo@shippo.com",
  ...
}
```

***

## Bypass address validation for label purchase

When purchasing shipping labels you can bypass the carrier's built-in address validation of some carriers by setting the Shipment object's `extra` field `bypass_address_validation` to `true`:

```json theme={null}
{
  /* insert other required shipment fields */
  "extra": {
    "bypass_address_validation": true
  }
}
```


# Shippo API release notes
Source: https://docs.goshippo.com/api-concepts/api-change-log

Track backwards-compatible and backwards-incompatible changes in each Shippo API version release.

We will be documenting all backwards-incompatible and backwards-compatible changes associated with each new API version here. [Learn more about how Shippo API versioning works and upgrade to the latest.](/api-concepts/api-versioning)

<Info>
  **Note**

  To learn about updates to Shippo Elements view the [Shippo Elements release notes](/shipping-elements/elements-change-log).
</Info>

## Version 2018-02-08

### Jul 23 2026

Minor: The Shippo MCP server is now listed in [Claude's connector directory](https://claude.ai/directory/connectors/shippo) and [ChatGPT's app directory](https://chatgpt.com/plugins/plugin_asdk_app_6a3be8ce7d0c81918cb8bcc8f6d0008e), so in Claude (claude.ai and Claude Desktop) and in ChatGPT you can add Shippo from the directory in one click and sign in with your Shippo account; there is no API key to manage. See the [MCP Server guide](/guides/mcp-server).

### Jul 16 2026

Minor: For MCP clients that can only launch local (stdio) servers, we published [`@shippo/shippo-mcp`](https://www.npmjs.com/package/@shippo/shippo-mcp) v3, a thin local bridge to the hosted Shippo MCP server. It signs you in with OAuth in your browser; there is no API key to manage. See the [MCP Server guide](/guides/mcp-server).

### Jul 10 2026

Minor: The Shippo MCP server is now listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/) as `com.shippo/shippo-mcp`, so MCP clients with registry-based discovery can find and add it by name.

### Jun 24 2026

Patch: FedEx rate responses now correctly return both the standard rate and the FedEx One Rate variant for eligible service levels, distinguishable via `servicelevel.terms: "ONERATE"` sharing the same `servicelevel.token` as the standard rate. See [Carrier capabilities: FedEx](/carriers/carrier-capabilities#fedex).

### Jun 4 2026

Minor: Shippo now offers a hosted MCP (Model Context Protocol) server at `https://mcp.shippo.com`. Connect AI assistants such as Claude, ChatGPT, and Cursor to your Shippo account to compare rates, buy labels, track packages, and validate addresses in natural language. Sign in with your Shippo account; there is no API key to manage. See the [MCP Server guide](/guides/mcp-server).

### Apr 7 2026

Minor: We've removed CDL from our list of supported carriers.

### Apr 6 2026

Minor: Shipment and Rate objects are now only retrievable for up to 390 days after creation. This applies to the following endpoints:

* [`GET /shipments`](/api-reference/shipments/list-all-shipments)
* [`GET /shipments/{ShipmentId}`](/api-reference/shipments/retrieve-a-shipment)
* [`GET /shipments/{ShipmentId}/rates`](/api-reference/rates/retrieve-shipment-rates)
* [`GET /rates/{RateId}`](/api-reference/rates/retrieve-a-rate)

### Mar 5 2026

Minor: The Shippo API now supports `include_package_details` as an optional boolean parameter in the Tracking `POST` request to return carrier-provided `weight` and `dimensions` in tracking responses for UPS and FedEx. See [Including package details](/tracking/tracking#including-package-details).

### Mar 4 2026

Minor: To support the new multi-factor verification flow for FedEx accounts, we created a new field on the `GET /carrier_accounts` endpoint to indicate if the verification process is required or not.  Review the [List Carrier Accounts](/api-reference/carrier-accounts/list-all-carrier-accounts) documentation for more details

### Mar 2 2026

Minor: ETA field for USPS tracking now uses USPS's Predicted Delivery Date as a fallback to the current Expected Delivery Date. This changes only the source of the ETA for USPS deliveries and has no impact on the API schema.

### Jan 19 2026

Minor: We've removed Sendle from our list of supported carriers.

### Jan 13 2026

Minor: Existing FedEx BYOA account users need to re-register their accounts before 3/31, or their label purchases may be disrupted. See our [FedEx Reconnecting Your Account Guide](/carriers/fed-ex-reconnecting-account) for step-by-step instructions.

### April 30 2025

Minor: We've enabled Windsor Framework to handle shipments from Great Britain to Northern Ireland as international shipments.

### Feb 19 2025

Minor: We've enabled Ground Plus and Premium Economy service levels for Veho

### Jan 14 2025

Patch: If the shipment was lost and its delivery failed we expect carriers to conduct an investigation in some cases and provide more tracking history events in case they are able to recover the shipment.

### Dec 17 2024

Minor: We've removed CouriersPlease from our list of supported carriers.

### Dec 16 2024

Minor: Switzerland are changing their requirements for shipping into the country. For more details, see [our guide](/international-shipping/international-shipping#shipping-to-switzerland-ch).

### Nov 26 2024

Minor: We've removed OrangeDS from our list of supported carriers.

### Oct 17 2024

Patch: Australia Post eParcel rate requests no longer filter out service levels with optional signature confirmation when the user does not explicitly request signature confirmation.

### Oct 8 2024

We have added an automated email to inform you when your [Pro Plan](https://support.goshippo.com/hc/en-us/articles/360003855652-Shippo-Subscription-Plan-Overview#h_01HNGBRQ4NXCKXWMCYQSQHC666) Free Trials start and expire.

### Sep 12 2024

Minor: On `Sep 16 at 00:00:00 CDT` we will enable CeC NSA account holders whose USPS rates are based on Merchant Rate Cards (MRC) to charge Commercial Plus Pricing (CPP) rates. They will receive Rural Partner Rate Cards (PRC) for a limited list of destination zip codes.

### Sep 11 2024

Minor: We've enabled Fedex Home Delivery® service level for Shippo's Fedex account.

### Sep 9 2024

Patch: We've fixed an issue where certain address `street2` formats were not printed on labels.

### Aug 29 2024

Patch: We've fixed an issue where some UPS tracking histories contained premature `delivered` events.

### Aug 15 2024

Patch: We have fixed an issue where tracking invoice item descriptions were incorrectly displaying "International address validation fee"

### Aug 13 2024

Minor: We've removed Parcel and Yodel from our list of supported carriers.

### Aug 7 2024

Patch: We have resolved an issue where logged-in users without a saved payment method could become stuck during partner-initiated OAuth authorization requests.

### Aug 5 2024

Minor: We've updated the Shippo API to support parcel tracking for a large number of carriers previously unsupported. See our [guide for details](/tracking/tracking-carrier).

### Jul 30 2024

Patch: We've removed a step in label purchase which prompted users to add a new payment method if they had unpaid invoices.

### Jul 15 2024

Minor: We've removed Maergo from our list of supported carriers.

### Jun 25 2024

Minor: We've added support for the Sendle drop off service.

### Jun 24 2024

Patch: Previously, when you purchased a shipping label through Shippo, the [tracking status](/api-reference/tracking-status/get-a-tracking-status) for that shipment would start with `UNKNOWN`. We've updated our tracking life cycle to start with `PRE_TRANSIT`. Review our [definitions of tracking events](/tracking/tracking#event-definitions) for more details.

### Jun 14 2024

Minor: The carrier AxleHire has changed its name to Jitsu. We have updated our guides to reflect this new name. To support our existing customers already using this carrier, we will continue to use the `axlehire` token.

### Jun 10 2024

Minor: As part of our continuing work to improve our SDKs, we've release a new [C# SDK for the Shippo API](/guides/client-libraries#c).

### May 10 2024

Minor: We've updated our UPS integration to include more label reference fields for ZPL II labels. See our [carrier reference fields](/carriers/carrier-reference-fields#add-additional-details-to-a-ups-label) guide for more details.

### Apr 30 2024

Minor: We've further increased the number of parcels you can send in a multi-piece shipment for UPS up to 200 parcels. Read our [multi-piece shipping guide](/shipments/multi-piece-shipment#create-an-extended-multi-piece-shipment) for more details.

### Apr 29 2024

Patch: We've made updates our [address validation](/api-reference/addresses/validate-an-address) process to improve how we classify the response. Now, the returned `validation_results` provide clearer `text` descriptions, helping you identify and correct any issues with an address.

### Apr 24 2024

Minor: We've increased the number of parcels you can send in a multi-piece shipment for UPS. Read our [multi-piece shipping guide](/shipments/multi-piece-shipment#create-a-multi-piece-shipment) for more details.

### Apr 24 2024

Minor: We've release a new [Javascript SDK for the Shippo API](/guides/client-libraries#nodejs).

### Apr 9 2024

Minor: In the future UPS will require users to use OAuth to authorize Shippo to perform some actions, like requesting rates or buying labels, on your behalf. To support this, we have created a new endpoint `carriers/{carrier_account_id}/signin/initiate` that directs a user to an OAuth flow. Review our [Carrier authorization using OAuth](/carriers/carrier-o-auth) guide for more details.

### Apr 8 2024

Minor: We've updated the Shippo API to support our new policy for automatically refunding unused USPS labels. From now on, we will no longer automatically refund unused USPS labels. You must create a request to receive a refund for unused labels. See our [Refunding labels](/billing-and-invoices/refunding-labels) guide for more information.

### Apr 1 2024

Minor: We are updating our API SDKs. As part of this work, we've released a [Python SDK for the Shippo API](/guides/client-libraries#python).

### Mar 1 2024

Minor: Our shipping insurance provider, XCover, have updated their terms. For shipments originating from the US, XCover now has a 25% deductible for Jewelry/Watches, Antiques/Artwork, and Glassware/Ceramics. See our [guide](/shipments/shipping-insurance#insurance-for-single-package-shipments-using-xcover) for details.

### Feb 28 2024

Minor: We’ve add support for the carrier [Veho](/carriers/carrier-capabilities#veho).

### Dec 8 2023

Minor: We've added support for A5 PDF labels for [Australia Post](/carriers/carrier-capabilities#australia-post) shipments.

### Aug 31 2023

Minor: We have added [XCover](https://www.xcover.com/en-us/help/partners/shippo) as our new insurance provider. To add XCover insurance to your packages, follow our [Shipping insurance](/shipments/shipping-insurance) guide.

### Aug 18 2023

Minor: We've updated our API to improve the accuracy of the time in transit information for all domestic USPS shipping rates.

### Jul 31 2023

Minor: FedEx have retired their Collect on Delivery (COD) service for FedEx Express and FedEx Ground COD service for shipments within and to the US from Canada. Now, when you create a shipment in the Shippo API and [include the option for COD](/api-reference/shipments/list-all-shipments), the rates returned will not include rates from FedEx.

### Jul 9 2023

Minor: We've added a new service level token to enable [USPS Ground Advantage](https://www.usps.com/ship/ground-advantage.htm). To use USPS Ground Advantage, use the token `usps_ground_advantage`. See the full list of [service tokens in our reference guide](/api-reference/service-groups/list-all-service-groups) for more information.

### Jun 15 2023

Minor: Hazardous materials or hazmat are items that can cause harm to people. When shipping with USPS, you must declare if your parcel contains hazmat items. To support our users compliance shipping hazmat items with USPS, we've added the `dangerous_goods` field to our `shipments`. See our [hazmat guide](/shipments/hazmat) for more details.

### Mar 10 2023

Minor: In the [Shipment Extras](/api-reference/shipments/list-all-shipments) object, we've added new fields to support FedEx labels.
Shipment Extras now includes the fields `customer_reference`, `po_number`, `invoice_number`, `dept_number`, and `rma_number`.

### Apr 25 2023

Minor: We've added [Platform Accounts](/platform-accounts/platform-accounts) to our API. Using a Platform Account, you can create and control Managed Shippo Accounts. Managed Shippo Accounts are headless accounts that are typically used by Marketplaces, e-commerce platforms, and third-party logistics. Using a Platform Account, you can make requests to the Shippo API on behalf of your Managed Accounts.
Use Shippo Platform Accounts to create a shipping experience that is seamless to your end customers.

### Dec 14 2022

Minor: You can now use QR codes for UPS. Generated QR codes can be brought to a carrier location to print labels for outbound and return shipments.

### Dec 9 2022

Minor: We’ve added support for insuring DHL eCommerce packages using our insurance provider, Shipsurance.

### Dec 7 2022

Patch: Previously, for Australia Post, some ZPL formatted labels were formatted incorrectly. We’ve fixed this formatting issue.

### Nov 23 2022

Patch: For Australia Post, some customers received this error message "The carrier API timed out. Please try again. If this error persists please contact support.". We have resolved this issue.

### Nov 17 2022

Minor: We’ve added the option to include the IOSS number for DPD UK using the API carrier request call.

### Nov 16 2022

Minor: For the carrier APG, we’ve added support for the service level “APG eParcel Expedited".

Patch: Previously, for some DPD packages, the status field would not be updated when the package was delivered. This has now been fixed.

### Nov 10 2022

Minor: FedEx has changed the names of it’s service Smartpost to Ground Economy. To support this we have added the service level token `fedex_ground_economy`. Any request made using the old token, `fedex_smart_post`, will be given the Ground Economy service level.

Minor: We have removed support for GLS DE and GLS FR.

### Nov 8 2022

Minor: For the carrier LaserShip, we’ve added support for users to define the critical\_pull\_time HH:MM format in carrier account parameters.

### Nov 2 2022

Patch: We’ve fixed an issue where the Orders endpoint was failing to update for batch entry.

### Oct 25 2022

Minor: We’ve add support for the carrier Better Trucks.

Minor: For Evri, we’ve updated our tracking URL for Evri from the old Hermes UK URL.

Patch: We’ve improved our error code reporting for Lasership.

### Oct 19 2022

Minor: For APG, we’ve added support additional service of Destroy for undeliverable packages.

### Sep 28 2022

Patch: We fixed an issue with the carrier APG that required a “state” in the address object.

Minor: For Evri, we’ve added Puerto Rico (PR) and Virgin Islands US (VI) as destination countries for parcelshop drop off service level

Patch: We’ve added a fix that removes special characters in post codes for DPD UK.

Minor: We’ve added Shippo carrier accounts for Post IT and Mondial. You can now use these carriers with the Shippo account.

### Sep 27 2022

Minor: We’ve added support for the carrier DPD DE.

### Sep 21 2022

Patch: For the carrier Evri we’ve fixed the issue causing the error message "Content Values do not add up to Parcel Value".

### Sep 15 2022

Minor: We’ve added Shippo carrier accounts for Chronopost. You can now use these carriers using the Shippo account.

### Sep 13 2022

Minor: We’ve add the carrier UDS to our list of supported carriers.

### Sep 9 2022

Minor: We’ve added support for our Canadian users to access the Shippo UPS account. This means that Shippo customers in Canada can benefit from the great rates we’ve negotiated with UPS.

### Sep 8 2022

Minor: We now support test mode for the carrier Swyft.

### Sep 1 2022

Minor: Previously we supported Evri only for domestic shipments. Now, we support Evri deliveries to European and the rest of the world from the UK.

Minor: We now support test mode for the carrier UDS.

### Jun 21 2022

Minor: The carrier Poste Italiane is now supported in the Shippo API.

### Jun 20 2022

Minor: We’ve added the carriers APG and Correos to our list of supported carriers.

### May 13 2022

Minor: The carrier Chronopost is now supported in the Shippo API.

### May 10 2022

Minor: Shippo’s customs now support Merchant Tax ID/VAT for international shipments.

### May 7th 2022

Minor: Shippo’s customs now support the EORI number for shipments to/from the EU & UK.

### Mar 2nd 2022

Minor: The carrier Colissimo is now part of list of supported carriers.

### Jan 14th 2022

Minor: We’ve added X Delivery to list of supported carriers

### Dec 14th 2021

Minor: You can now use the carrier DPD UK in the Shippo API

### July 28th 2021

Minor: We’ve added Royal Mail to our list of supported carriers.

### Jul 15th 2022

Minor: Our Customs Declaration object now includes the field `is_vat_collected`. You can use this field to indicate whether the shipment’s destination VAT has been collected. This is required for some destinations.

### Jun 16th 2022

Patch: We’ve fixed a bug to ensure only valid service levels are returned when getting shipping rates.

### Dec 10th 2021

Minor: Previously, when calling our list parcels endpoint, you might have received a very long list of results. To help, we’ve added pagination to help control the results you see.

### Aug 17 2021

Minor: We’ve added `extended_token` and `parent_servicelevel` fields to our Rates object. These fields give you clearer insight into specific service levels quoted in a Rate. Some service levels, like those for UPS,  are grouped, and are represented by a generic token. For example, the token `ups_expedited` represents service levels including `ups_expedited_ca` and `ups_expedited_eu`. In this example,  `parent_servicelevel` would return `ups_expedited`. `Extended_token` could return one of `ups_expedited_ca` and `ups_expedited_eu`.

### May 10 2021

Minor: The carrier GLS US is now supported in our API.

### Apr 9 2021

Minor: In customs declarations, you can now add a tax identification number and Employer Identification Number. These are required for some international shipment.

### Sep 10 2020

Minor: To aid international shipments, we’ve added some new customs fields. In our customs declarations, we’ve added the fields to support B13A. We’ve also added fields in our customs items to support ECCN.

### Aug 7 2020

Minor: We’ve added support for the carrier PCF to our API.

### July 30 2020

Minor: We’ve added a field for qr codes to the Transaction object. If supported by the carrier, the `qr_code_url` will contain a link to a  QR code image.

### Apr 4 2020

Minor: We’ve added the carrier OrangeDS to our list of supported carriers.

### Feb 24 2020

Minor: You can use the carrier LSO to ship packages using our API.

### May 10 2019

Minor: The Shipment object now includes the field `alternate_address_to` that you can use to set an alternate delivery address.

### Apr 24 2019

Minor: The Customs Declaration object now includes a `duty_payor` field. Using this field you can define who is paying for the duties of international shipments. This is required by some carriers.

### Dec 19th 2018

Minor: We’ve added support for the carrier CDL to our API.

### Oct 19 2018

Minor: We’ve added AxleHire to our list of supported carriers.

### Sept 5 2018

Minor: We’ve added a new `validation_status` field ot our Orders endpoint. Now, when you retrieve an Order, you will get an `validation_status` parameter to show if the created Order object is `pending`, `valid`, or `invalid`.

### Aug 28 2018

Minor: We’ve added an error field to our Orders endpoint. Now, when you retrieve an Order, you will get an “error” parameter that includes any error messages associated with your Order object.

### Apr 13 2018

Minor: For security reasons, the `account_id` and `parameters` fields will be censored in the response objects for Carrier Accounts.

### Mar 19 2018

Minor: We’ve added Globegistics to our list of supported carriers.

### Feb 15 2018

Minor: We've added support for the carrier CouriersPlease to our API.

### Jan 22 2018

Minor: You can use the carrier Sendle to ship packages using our API.

### 8 Feb 2018

Minor: PRE\_TRANSIT will be added to the list of possible values in `status`.

Minor: PRE\_TRANSIT will be added to the list of possible values in `status` and `tracking_status` for `track_updated` and `transaction_updated` events, respectively.

## Version 2017-08-01

### Webhooks

`Shippo-API-Version` will be included in the headers of all webhook responses to indicate the api version being used.

New events have been added to our webhooks:

* `transaction_updated` -- will be triggered when a transaction in your account is updated, and will provide the updated transaction.
* `transaction_created` -- will be triggered when a transaction in your account is created, and will provide the updated transaction.

A new fields have been added in the body of the webhook payload:

* `event_type` will have one of the following values: `transaction_created`, `transaction_updated`, `track_updated`, `batch_created`, or `batch_updated`.

Please see our [Webhooks](/tracking/webhooks) tutorials for examples of using these new fields and events.

### All Endpoints

The `count` field has been removed. If making a GET request to any endpoint without an `object_id` specified in the URI (i.e. /transactions, /shipments, /addresses) you will no longer see the `count` field in the body of the response.

### Rates

In rate objects, the `days` field has been renamed to `estimated_days` to make it clear that this is an estimate.

### Transactions

The `tracking_history` field has been deprecated from the Transactions object. The Transactions object will still have the most recent `tracking_status` on it, but to get a full tracking history, you would need to subscribe a[webhook](/tracking/webhooks) to the `tracking_update` event or query the [Tracks](/api-reference/tracking-status/get-a-tracking-status) endpoint.

## Version 2017-03-29

### Major Update: Refactored and Deprecated Fields

In this API version, we've cleaned up many stale attributes across various endpoints in the API to make them more intuitive and true to operational use cases. Please explore the following to see if any changes will affect your implementation.

The changes to our Shipments endpoint for [returns](/shipments/returns) now makes it possible to create return labels without having to reference a previous transaction.

Changes have been made to the following endpoints: [Addresses](/api-reference/addresses/list-all-addresses), [Shipments](/api-reference/shipments/list-all-shipments), [Rates](/api-reference/rates/retrieve-a-rate), [Transactions](/api-reference/transactions/list-all-shipping-labels), [Batches](/api-reference/batches/create-a-batch), and [Refunds](/api-reference/refunds/list-all-refunds). For more detailed information, please see the [full API references](/api-reference/addresses/list-all-addresses).

### Addresses

Request:

* Deprecated:

  * `object_purpose`

Response:

* Deprecated:

  * `ip`
  * `object_purpose`
  * `object_state`
  * `object_source`
* Added:

  * `is_complete` --- boolean used to indicate if an address is fully entered, making it possible to use for purchasing a label.
  * `validation_results` --- object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are `is_valid`(boolean) and `messages`(array).
* Updated:

  * `messages` has been moved into new `validation_results` field.

### Shipments

Request:

* Deprecated:

  * `object_purpose`
* Updated:

  * `submission_date` is now `shipment_date`
  * `return_of` is now `is_return`, also has been changed to a boolean and is no longer a top-level key and has been moved into extra field. This will flag a shipment to be created as a scan-based label.
  * `object_status` is now `status`
  * `insurance_amount` is now `amount`, moved into newly added`insurance` field inside `extra`object.
  * `insurance_currency` is now `currency`, moved into newly added `insurance` field inside `extra` object.
  * `insurance_provider` is now `provider`, moved into newly added `insurance` field.
  * `insurance_content` is now `content`, moved into newly added `insurance` field.
  * `reference_1` & `reference_2` moved to `extra` field.
  * `parcel` is now `parcels` and has been changed to an array.
* Added:
  * `insurance`, an object within the `extra` object with previous top level and `extra` level insurance fields as keys of the `insurance` object.

Response:

* Deprecated:

  * `object_state`
  * `submission_type`
  * `object_purpose`
  * `rates_url`
* Updated:

  * `rates_list` is now `rates`
  * `submission_date` is now `shipment_date`
  * `return_of` is now `is_return`, also has been changed to a boolean and is no longer a top-level key and has been moved into the `extra` field. This will set the shipment as a return shipment, which makes the label scan-based. See our docs on [Returns](/shipments/returns) for more information.
  * `object_status` is now `status`
  * `insurance_amount` is now `amount`, moved into newly added`insurance` field.
  * `insurance_currency` is now `currency`, moved into newly added `insurance` field.
  * `insurance_content` is now `content`, moved into newly added `insurance` field.
  * `insurance_provider` is now `provider`, moved into newly added `insurance` field.
  * `reference_1` & `reference_2` moved to `extra` field.
  * `address_to`,`address_from`, `address_return`, and `parcel` are now expanded to include full address or parcel information, in addition to their `object_id`.
  * `parcel` is now `parcels` and has been changed to an array.
* Added:

  * `insurance`, an object within the `extra` object with previous insurance fields as keys of the `insurance` object.

### Rates

Request:

* Deprecated:

  * GET on /rates/ will no longer return a list of rates. GET on /rates/`{object_id}` will still work as indicated.

Response:

* Deprecated:

  * `object_state`
  * `object_purpose`
  * `object_updated`
  * `trackable`
  * `delivery_attempts`
  * `rates_url`
* Updated:

  * `servicelevel_name`, `servicelevel_token`, and `servicelevel_terms` have been renamed to `name`, `token`, and `terms`(respectively) and moved into the newly created `servicelevel`field.
* Added:

  * `servicelevel`, object that contains renamed fields: `name`, `token`, and `terms`(previously `servicelevel_name`, `servicelevel_token`, and `servicelevel_terms`)

### Transactions

Response:

* Deprecated:

  * `customs_note`
  * `submission_note`
* Updated:

  * `object_state` is now `status`
  * `rate` field is expanded with full rate details for insta-label calls.

### Manifest

Request:

* Updated:

  * `submission_date` is now `shipment_date`

Response:

* Updated:

  * `submission_date` is now `shipment_date`

### Batches

Response:

* Updated:

  * `object_status` is now `status`

### Refunds

Response:

* Updated:

  * `object_status` is now `status`

### Parcel

Request:

* Updated:

  * `reference_1` and `reference_2` can be added in the `extra` field of Parcel for multi-parcel shipments. See [Multi-Piece Shipments](/shipments/multi-piece-shipment) for more information.

## Version 2016-10-25

### Major Update: New Test Token used to set Shippo to test mode.

You will now be able use all Shippo API functionalities from end-to-end in test mode by authenticating requests with a Test Token. Previously, to test out Shippo, you had to set carrier accounts to test mode. Now all users will have have two different tokens: one for test mode and one for live mode.

[See our detailed documentation on Test Mode.](/guides/testing)

### For users continuing to use API version 2014-02-11

You will have the option of using the Test Token while remaining on the older version of the Shippo API.

* Test Token can be used for test mode without affecting your existing implementation. See our [Test Mode documentation](/guides/testing) to learn more about functionalities.
* Functionalities of your existing Private Auth Token will remain the same -- now renamed as "Live Token".
* All tokens will now begin with `"shippo_live_"` or `"shippo_test_"`. This will not affect any existing implementation with old tokens, however we recommend using the new format going forward.

### For users upgrading to API version 2016-10-25

Using the Test Token and Live Token will affect how your test and live data are returned and displayed.

Test and Live Data

* When using the Test Token, you will only be able to create and request test data sets such as addresses, rates, and carriers etc. No live data can be requested or returned.
* When using the Live Token, you will only be able to create and request live data. No test data can be requested or returned.
* Shipment object will now return 3 variables for `test`
  * True -- All Rates returned in Shipment were tests
  * False -- All Rates returned in Shipment were live
  * None -- Rates returned in Shipment were both tests and live

The following are some common scenarios.

1. If you create a Shipment with Live Token using an Address object created with a Test Token, you will receive a 404 response (not found). Vice versa is also true. If you retrieve an object\_id created in live mode with a Test Token, you will receive a 403 (bad request) response.
2. If you request a list of Transaction objects, or Shipment objects with the Test Token, only test Transactions or Shipments will be returned. Vice versa is also true, when making requests in live mode.

Carrier account configuration

When you upgrade to the latest version, the `test` attribute of the carrier object will become read-only.

* User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to `test: true` at the time of upgrade will only appear and work when request with a Test Token.
* User-owned carrier accounts (where you have plugged in your own carrier credentials) that have been set to `test: false` at the time of upgrade will only appear and work when request with a Live Token.
* Shippo-owned carrier accounts [(see carrier capabilities for full list)](/carriers/carrier-capabilities) object\_ids will appear and be functional when requested with a Test Token or a Live Token.

We recommend setting all carrier accounts to `test: false` [(including on your dashboard)](https://goshippo.com/user/carriers/) before upgrading so that existing carrier accounts are set to live mode. This will help with minimizing changes necessary for the upgrade.

"test" attribute

Certain objects will now be returning a new `"test"` attribute.

* Transaction object will no longer return the "was\_test" attribute, instead it will return "test".
* Address, Parcel, Refund, Customs Declaration, and Customs Items objects will now return a new "test" attribute.
* Possible values for "test":
  * True -- the object was created in test mode
  * False -- the object was created in live mode
* Other objects (such as Carrier Accounts and Rates) will keep returning "test" if they did in past.


# Expand response
Source: https://docs.goshippo.com/api-concepts/api-expand

Learn how to use the expand query parameter to include full object details in Shippo API responses.

In some Shippo API responses, instead of returning parameters, the endpoint will return the object ID of the object that contains the parameters. This is available for a number of Shippo objects.

For example, in the transaction response, the `rate` is returned as an object ID. The Shippo API is designed in this way to manage the size of the response.

**Request:**

```shell Get a transaction theme={null}
curl --location 'https://api.goshippo.com/transactions/3e294ad43f7e417889c3c3766df2589b' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

**Response:**

```json response sample theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2024-04-23T16:03:01.881Z",
    "object_updated": "2024-04-23T16:03:04.906Z",
    "object_id": "3e294ad43f7e417889c3c3766df2589b",
    "object_owner": "mrhippo@goshippo.com",
    "test": true,
    "rate": "819282d7ec8d4b1db3d03bbf8f0e1a7d",
    "tracking_number": "EB000098472US",
    "tracking_status": "UNKNOWN",
}

```

You can choose to expand an object using the query parameter `expand`. When you expand an object, the returned response includes the parameters in that object.

**Request:**

```shell Get a transaction including expand request theme={null}
curl --location 'https://api.goshippo.com/transactions/3e294ad43f7e417889c3c3766df2589b?expand="rate"' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

**Response:**

```json Get a transaction including expand response theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2024-04-23T16:03:01.881Z",
    "object_updated": "2024-04-23T16:03:04.906Z",
    "object_id": "3e294ad43f7e417889c3c3766df2589b",
    "object_owner": "mrhippo@goshippo.com",
    "test": true,
    "rate": {
        "object_id": "819282d7ec8d4b1db3d03bbf8f0e1a7d",
        "amount": "76.66",
        "currency": "USD",
        "amount_local": "71.95",
        "currency_local": "EUR",
        "provider": "USPS",
        "servicelevel_name": "Priority Mail Express International",
        "servicelevel_token": "usps_priority_mail_express_international",
        "carrier_account": "b19e750708384303ac19ca693fe037ce"
    },
    "tracking_number": "EB000098472US",
    "tracking_status": "UNKNOWN",
}
```

You can choose to expand multiple objects together at once using an array.

```shell Get a transaction including expand multiple objects theme={null}
curl --location 'https://api.goshippo.com/transactions/3e294ad43f7e417889c3c3766df2589b?expand=["rate","parcel"]' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

This method does not support recursion.


# API objects
Source: https://docs.goshippo.com/api-concepts/api-objects

Understand how Shippo API objects and object IDs work, and learn how to create, retrieve, and use them.

## What is a Shippo API Object?

Read this guide to understand how the Shippo API uses objects and object IDs.

In the Shippo API, objects use used to stored information. Objects are stored in the Shippo database. Examples of objects include addresses, carrier accounts, transactions, and labels.

Each object has an associated object ID. Each object ID is unique and you can use the object ID to reference and use the data in the object.

Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Most objects in the Shippo API are immutable. This means that once you have created an object, you cannot change it. Instead, you must create a new one with the updated values.
`Carrier Accounts`, `Service Groups`, and `User Parcel Templates` are the only objects that you can update.

## How to use a Shippo API object

Follow this example to help understand how to use Shippo API objects.

Before starting this example, make sure you have generated your [test token](/guides/authentication). In each example, replace `<API_TOKEN>` with the test token you have generated.

### <img alt="Step 1" /> Create an address object

<CodeGroup>
  ```shell cURL theme={null}
   curl https://api.goshippo.com/addresses/ \
      -H "Authorization: ShippoToken <API_TOKEN>" \
      -d name="Shawn Ippotle" \
      -d company="Shippo" \
      -d street1="215 Clayton St." \
      -d street2="" \
      -d city="San Francisco" \
      -d state="CA" \
      -d zip=94117 \
      -d country="US" \
      -d phone="+1 555 341 9393" \
      -d email="shippotle@shippo.com"\
      -d is_residential=True\
      -d metadata="Customer ID 123456"
  ```

  ```Python Python theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  shippo_sdk.addresses.create(
      components.AddressCreateRequest(
          name="Shawn Ippotle",
          company="Shippo",
          street1="215 Clayton St.",
          city="San Francisco",
          state="CA",
          zip="94117",
          country="US", # iso2 country code
          phone="+1 555 341 9393",
          email="shippotle@shippo.com"
      )
  )
  ```

  ```PHP PHP theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_TOKEN>");

  // Create address object
  $fromAddress = Shippo_Address::create( array(
      "name" => "Shawn Ippotle",
      "company" => "Shippo",
      "street1" => "215 Clayton St.",
      "city" => "San Francisco",
      "state" => "CA",
      "zip" => "94117",
      "country" => "US",
      "phone" => "+1 555 341 9393",
      "email" => "shippotle@shippo.com"
  ));
  ```

  ```typescript TypeScript theme={null}
  // Create address object
  const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>'});
  const addressFrom = await shippo.addresses.create({
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US", // iso2 country code
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com",
  });
  ```
</CodeGroup>

The expected response is a view of the address object that includes the address you created along with its metadata.
It includes the object ID, `"object_id"` that you can use to reference the object.

```json theme={null}
{
"is_complete": true,
   "object_created":"2022-07-09T02:19:13.174Z",
   "object_updated":"2022-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@shippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@shippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}
```

### <img alt="Step 2" /> Use this object ID to retrieve the address details

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \
      -H "Authorization: ShippoToken <API_TOKEN>"
  ```

  ```Python Python theme={null}
  # Retrieve an existing address by object_id
  shippo_sdk.addresses.get("d799c2679e644279b59fe661ac8fa488")
  ```

  ```PHP PHP theme={null}
  // Retrieve an existing address by object_id
  Shippo_Address::retrieve('d799c2679e644279b59fe661ac8fa488');
  ```

  ```typescript TypeScript theme={null}
  // Retrieve an existing address by object_id
  shippo.addresses.get('d799c2679e644279b59fe661ac8fa488');
  ```
</CodeGroup>

In this example, `d799c2679e644279b59fe661ac8fa488` is the object ID of the address you have created.

The expected response is a view of the address object that includes the address you created along with its metadata. The same response you received when you created the address object.

```json theme={null}
{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@shippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@shippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456",
   "test": true
}
```

## Shippo API object list

The following is a list of objects created in the Shippo API.

| Object                                                                                          | Object Name                |
| ----------------------------------------------------------------------------------------------- | -------------------------- |
| [Address Object](/api-reference/addresses/list-all-addresses)                                   | AddressId                  |
| [Parcel Object](/api-reference/parcels/list-all-parcels)                                        | ParcelId                   |
| [User Parcel Object](/api-reference/user-parcel-templates/list-all-user-parcel-templates)       | UserParcelTemplateObjectId |
| [Shipment Object](/api-reference/shipments/list-all-shipments)                                  | ShipmentId                 |
| [Rate Object](/api-reference/rates/retrieve-a-rate)                                             | RateId                     |
| [Transaction Object](/api-reference/transactions/list-all-shipping-labels)                      | TransactionId              |
| [Batch Object](/api-reference/batches/create-a-batch)                                           | BatchId                    |
| [Customs Item Object](/api-reference/customs-items/list-all-customs-items)                      | CustomsItemId              |
| [Customs Declaration Object](/api-reference/customs-declarations/list-all-customs-declarations) | CustomsDeclarationId       |
| [Carrier Account Object](/api-reference/carrier-accounts/list-all-carrier-accounts)             | CarrierAccountId           |
| [Manifest Object](/api-reference/manifests/list-all-manifests)                                  | ManifestId                 |
| [Pickup Object](/api-reference/pickups/create-a-pickup)                                         | PickupId                   |
| [Order Object](/api-reference/orders/list-all-orders)                                           | OrderId                    |
| [Refund Object](/api-reference/refunds/list-all-refunds)                                        | RefundId                   |
| [Invoice Object](/api-reference/addresses/list-all-addresses)                                   | InvoiceObjectId            |
| [Service Group Object](/api-reference/service-groups/list-all-service-groups)                   | ServiceGroupId             |
| [Shippo Account Object](/api-reference/shippo-accounts/list-all-shippo-accounts)                | ShippoAccountId            |


# Shippo API upgrade guide
Source: https://docs.goshippo.com/api-concepts/api-upgrade-guides/upgrade-guide

Step-by-step instructions to identify your current Shippo API version and safely upgrade to the latest.

## What does the API version mean?

The Shippo API has multiple versions. A new version is created any time we make “breaking changes” to our API. These are changes to our API that could cause your integration to not work correctly anymore.

We use versions to significantly improve and develop new features in our API, without affecting our existing users' experience. Versions allow you to continue to use older versions of the API until you’re ready to update your system to the latest version.

## Why should I upgrade?

We recommend staying up-to-date with the latest API version to take advantage of the latest improvements and features added to the Shippo API.

## Which Shippo API version do I use today?

There are two ways to set the Shippo API version.

The first way to set the version of the Shippo API you use, is linked to your account and was set when you first created your Shippo account.

To see your current API version linked with your account, follow these steps.

1. Log in to the [Shippo API Portal](https://portal.goshippo.com/api-config/api)
2. In the left menu, under "API Configuration", click “Developer keys”
3. Find the “API Version” section, your current API version is listed next to “Current version:”

<img alt="UI showing where API version is displayed" />

The second way that the Shippo API version is selected is within the code you use to integrate with the Shippo API. The API version specified in your code takes precedence over the version you have set in your Shippo account.
If you do not specify a version in your code, the version set in your Shippo account is used.

If you’ve integrated with the Shippo API through one of our [client libraries](/guides/client-libraries), refer to the library examples to check if your client library supports selecting your Shippo API version.

If you’ve integrated with the Shippo API using cURL, your API version may be set using the a header. For example `-H "Shippo-API-Version: YYYY-MM-DD”`.

## Upgrade

### Before you upgrade

1. Identify your current API version.
2. In your own code identify the Shippo endpoints you currently use.
3. Review our [changelog](/api-concepts/api-change-log) to see the changes to the endpoints that you use.
4. For your current API version, review the appropriate upgrade guides to quickly identify which object fields have changed.
   * If you are upgrading from v20140211, use [this guide](/api-concepts/api-upgrade-guides/v20140211-to-2018).
   * If you are upgrading from v20161025, use [this guide](/api-concepts/api-upgrade-guides/v20161025-to-2018).
   * If you are upgrading from v20170329, use [this guide](/api-concepts/api-upgrade-guides/v20170329-to-2018).
   * If you are upgrading from v20170801, use [this guide](/api-concepts/api-upgrade-guides/v20170801-to-2018).

### Upgrading a cURL integration

To upgrade safely, follow these steps. We recommend that you upgrade each API call one at a time.

1. Identify an API call to the Shippo API.
2. Change your authorization token to a [test token](/guides/testing). Using the test token means that you will not get charged and your live data will not be affected.
3. Manually add or change the Shippo API version in your API calls using the header `Shippo-API-Version`, setting your API version to the latest` `2018-02-08\`.

For example:

```shell theme={null}
curl https://api.goshippo.com/shipments/\
	-H "Authorization: ShippoToken <API_Token>"\
    		-H "Shippo-API-Version: 2018-02-08"\
    		-d '{ ... }'
```

4. Test the API call to confirm it is functioning as expected.
5. Complete steps 1 - 3 for each API call.
6. After you’ve tested each Shippo API call that your integration uses and you are confident it is functioning as expected, change your API token back to your live token and re-verify that they are functioning as expected. We recommend you keep the `Shippo-API-Version` in your API call as it is the preferred way to set your version.
7. After your final test, upgrade your API version linked with your Shippo account.

<Warning>
  **Warning**

  Warning: You cannot reverse an upgrade.
</Warning>

8. Follow the steps in [Which Shippo API version I’m I using today?](#which-shippo-api-version-do-i-use-today) and click “Updates available”.

<img alt="Image showing update is available" />

9. Review the warnings and when ready, check the confirmation checkbox, and click “Upgrade”.
   The process will take a couple of minutes to complete.
   Reminder: Do not do this until you have completely validated that the latest version works for your integration.

<img alt="Warning display before upgrading default API version" />

### Upgrading a client library integration

If you’ve integrated with the Shippo API through one of our [client libraries](/guides/client-libraries), refer to the library examples to check if your client library supports selecting your Shippo API version.

<Info>
  **note**

  We no longer actively maintain our client libraries. However, you can use them as a starting point and update them for your needs and future changes to our APIs. For more details about how you can use the Shippo API with your preferred language, see our [client libraries guide](/guides/client-libraries).
</Info>

#### Client library upgrade by selecting API version

If your client library does support the option to set the API version, follow these steps.

1. Change your authorization token to a [test token](/guides/testing). Using the test token means that you will not get charged and your live data will not be affected.
2. Manually add or change the Shippo API version in your script.  For example, in Python, use this command.

```python theme={null}
shippo.config.api_version = "2018-02-08"
```

3. Test your integration to confirm it is functioning as expected.
4. After you’ve tested your integration and you are confident it is functioning as expected, change your API token back to your live token and re-verify that it is functioning as expected.
5. After your final test, upgrade your API version linked with your Shippo account. Follow the steps [7,8, and 9](#upgrading-a-curl-integration).

#### Client library upgrade using Shippo account API version

If your client library does not support the option for selecting the Shippo API version, the API version you use is set in your Shippo account.
To upgrade, follow these steps.

1. Change your authorization token to a [test token](/guides/testing). Using the test token means that you will not get charged and your live data will not be affected.
2. Upgrade, following steps [7,8, and 9](#upgrading-a-curl-integration).
3. Test your integration to confirm it is functioning as expected.
4. After you’ve tested your integration and you are confident it is functioning as expected, change your API token back to your live token and re-verify that they are functioning as expected.


# Upgrading from v20140211 to v20180208
Source: https://docs.goshippo.com/api-concepts/api-upgrade-guides/v20140211-to-2018

Review deprecated and added fields when upgrading from Shippo API v20140211 to v20180208.

If you have already integrated with the Shippo API v20140211 and are now planning to upgrade to the latest version (v20180208), you can use this guide to identify which objects have changed between versions.

In these tables you will find the fields within each object have that have deprecated. In some cases, you can see a replacement field that has been added in v20180208.

## Deprecated ◎ and added ◉ fields

### Orders

| Resource   | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉     |
| ---------- | ---------------------------------- | ------------------------------- |
| **Orders** | address\_from                      | from\_address                   |
|            | created\_at                        |                                 |
|            | hidden                             |                                 |
|            | items                              |                                 |
|            | to\_address.ip                     |                                 |
|            | to\_address.messages               |                                 |
|            | to\_address.object\_purpose        |                                 |
|            | to\_address.object\_source         |                                 |
|            | to\_address.object\_state          |                                 |
|            |                                    | placed\_at                      |
|            |                                    | test                            |
|            |                                    | to\_address.is\_complete        |
|            |                                    | to\_address.validation\_results |
|            |                                    |                                 |

### Batches

| Resource    | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ----------- | ---------------------------------- | --------------------------- |
| **Batches** | object\_status                     | status                      |
|             |                                    |                             |

### Carrier Accounts

| Resource             | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| -------------------- | ---------------------------------- | --------------------------- |
| **Carrier Accounts** |                                    | carrier\_images             |
|                      |                                    | carrier\_images.200         |
|                      |                                    | carrier\_images.75          |
|                      |                                    | carrier\_name               |
|                      |                                    |                             |

### Manifests

| Resource      | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ------------- | ---------------------------------- | --------------------------- |
| **Manifests** | is\_test                           |                             |
|               | object\_status                     | status                      |
|               | submission\_date                   |                             |
|               |                                    | shipment\_date              |
|               |                                    |                             |

### Refund

| Resource   | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ---------- | ---------------------------------- | --------------------------- |
| **Refund** | object\_status                     | status                      |
|            |                                    |                             |

### Customs Declaration

| Resource                 | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ------------------------ | ---------------------------------- | --------------------------- |
| **Customs Declarations** |                                    | address\_importer           |
|                          |                                    | b13a\_filing\_option        |
|                          |                                    | b13a\_number                |
|                          |                                    | duties\_payor               |
|                          |                                    | exporter\_identification    |
|                          |                                    | invoiced\_charges           |
|                          |                                    | is\_vat\_collected          |
|                          |                                    |                             |

### Customs Items

| Resource          | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ----------------- | ---------------------------------- | --------------------------- |
| **Customs Items** |                                    | eccn\_ear9                  |
|                   |                                    |                             |

### Tracks

| Resource   | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ---------- | ---------------------------------- | --------------------------- |
| **Tracks** |                                    | tracking\_status.substatus  |
|            |                                    | substatus.text              |
|            |                                    | substatus.code              |
|            |                                    | substatus.action\_required  |
|            |                                    | description                 |
|            |                                    |                             |

### Transactions

| Resource         | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ---------------- | ---------------------------------- | --------------------------- |
| **Transactions** | customs\_note                      |                             |
|                  | notification\_email\_from          |                             |
|                  | notification\_email\_other         |                             |
|                  | notification\_email\_to            |                             |
|                  | object\_status                     | status                      |
|                  | pickup\_date                       |                             |
|                  | submission\_note                   |                             |
|                  | tracking\_history                  |                             |
|                  | was\_test                          | test                        |
|                  |                                    | billing.payments            |
|                  |                                    | billing                     |
|                  |                                    | qr\_code\_url               |
|                  |                                    |                             |

### Rates

| Resource  | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉       |
| --------- | ---------------------------------- | --------------------------------- |
| **Rates** | available\_shippo                  |                                   |
|           | days                               | estimated\_days                   |
|           | delivery\_attempts                 |                                   |
|           | inbound\_endpoint                  |                                   |
|           | insurance                          |                                   |
|           | insurance\_amount                  |                                   |
|           | insurance\_amount\_local           |                                   |
|           | insurance\_currency                |                                   |
|           | insurance\_currency\_local         |                                   |
|           | object\_purpose                    |                                   |
|           | object\_state                      |                                   |
|           | object\_updated                    |                                   |
|           | outbound\_endpoint                 |                                   |
|           | servicelevel\_name                 | servicelevel.name                 |
|           | servicelevel\_terms                | servicelevel.terms                |
|           | servicelevel\_token                | servicelevel.token                |
|           | trackable                          |                                   |
|           |                                    | servicelevel.extended\_token      |
|           |                                    | servicelevel.parent\_servicelevel |
|           |                                    | included\_insurance\_price        |
|           |                                    | servicelevel                      |
|           |                                    |                                   |

### Shipments

| Resource      | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉         |
| ------------- | ---------------------------------- | ----------------------------------- |
| **Shipments** | insurance\_amount                  |                                     |
|               | insurance\_currency                |                                     |
|               | object\_purpose                    |                                     |
|               | object\_state                      |                                     |
|               | object\_status                     |                                     |
|               | parcel                             |                                     |
|               | rates\_list                        |                                     |
|               | rates\_url                         |                                     |
|               | reference\_1                       |                                     |
|               | reference\_2                       |                                     |
|               | return\_of                         |                                     |
|               | submission\_date                   |                                     |
|               | submission\_type                   |                                     |
|               |                                    | address\_from.is\_complete          |
|               |                                    | address\_from.validation\_results   |
|               |                                    | address\_from.name                  |
|               |                                    | address\_from.street3               |
|               |                                    | address\_from.zip                   |
|               |                                    | address\_from.city                  |
|               |                                    | address\_from.state                 |
|               |                                    | address\_from.test                  |
|               |                                    | address\_from.object\_id            |
|               |                                    | status                              |
|               |                                    | address\_to.is\_complete            |
|               |                                    | address\_from.company               |
|               |                                    | address\_from.is\_residential       |
|               |                                    | address\_from.email                 |
|               |                                    | address\_from.country               |
|               |                                    | address\_from.phone                 |
|               |                                    | address\_from.street2               |
|               |                                    | address\_from.street1               |
|               |                                    | address\_from.street\_no            |
|               |                                    | address\_to.object\_id              |
|               |                                    | address\_return.city                |
|               |                                    | address\_return.company             |
|               |                                    | address\_return.country             |
|               |                                    | address\_return.email               |
|               |                                    | address\_return.is\_complete        |
|               |                                    | address\_return.is\_residential     |
|               |                                    | address\_return.name                |
|               |                                    | address\_return.object\_id          |
|               |                                    | address\_return.phone               |
|               |                                    | address\_return.state               |
|               |                                    | address\_return.street1             |
|               |                                    | address\_return.street2             |
|               |                                    | address\_return.street3             |
|               |                                    | address\_return.street\_no          |
|               |                                    | address\_return.test                |
|               |                                    | address\_return.validation\_results |
|               |                                    | address\_return.zip                 |
|               |                                    | address\_to.city                    |
|               |                                    | address\_to.company                 |
|               |                                    | address\_to.country                 |
|               |                                    | address\_to.email                   |
|               |                                    | address\_to.is\_residential         |
|               |                                    | address\_to.name                    |
|               |                                    | address\_to.phone                   |
|               |                                    | address\_to.state                   |
|               |                                    | address\_to.street1                 |
|               |                                    | address\_to.street2                 |
|               |                                    | address\_to.street3                 |
|               |                                    | address\_to.street\_no              |
|               |                                    | address\_to.test                    |
|               |                                    | address\_to.validation\_results     |
|               |                                    | address\_to.zip                     |
|               |                                    | alternate\_address\_to              |
|               |                                    | rates                               |
|               |                                    | parcels                             |
|               |                                    | shipment\_date                      |
|               |                                    |                                     |

| Resource      | Deprecated fields from v20140211 ◎ | Fields added in v20180208 ◉ |
| ------------- | ---------------------------------- | --------------------------- |
| **Addresses** | ip                                 |                             |
|               | messages                           |                             |
|               | object\_purpose                    |                             |
|               | object\_source                     |                             |
|               | object\_state                      |                             |
|               |                                    | is\_complete                |
|               |                                    | validation\_results         |

## Updated fields ◐

The following object fields have changed type in v20180208 since v20140211:

| Resource         | Field            | Field type in v20140211 | Field type changed to in v20180208 |
| ---------------- | ---------------- | ----------------------- | ---------------------------------- |
| **Orders**       | weight           | int                     | decimal                            |
| **Transactions** | tracking\_status | obj                     | str                                |
| **Shipments**    | address\_from    | str                     | Obj or address object id as a str  |
|                  | address\_to      | str                     | Obj or address object id as a str  |
|                  | address\_return  | str                     | Obj or address object id as a str  |


# Upgrading from v20161025 to v20180208
Source: https://docs.goshippo.com/api-concepts/api-upgrade-guides/v20161025-to-2018

Review deprecated and added fields when upgrading from Shippo API v20161025 to v20180208.

If you have already integrated with the Shippo API v20161025 and are now planning to upgrade to the latest version (v20180208), you can use this guide to identify which objects have changed between versions.

In these tables you will find the fields within each object have that have deprecated. In some cases, you can see a replacement field that has been added in v20180208.

## Deprecated ◎ and added ◉ fields

### Orders

| Resource   | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉     |
| ---------- | ---------------------------------- | ------------------------------- |
| **Orders** | address\_from                      | from\_address                   |
|            | created\_at                        |                                 |
|            | hidden                             |                                 |
|            | items                              |                                 |
|            | to\_address.ip                     |                                 |
|            | to\_address.messages               |                                 |
|            | to\_address.object\_purpose        |                                 |
|            | to\_address.object\_source         |                                 |
|            | to\_address.object\_state          |                                 |
|            |                                    | placed\_at                      |
|            |                                    | test                            |
|            |                                    | to\_address.is\_complete        |
|            |                                    | to\_address.validation\_results |
|            |                                    |                                 |

### Batches

| Resource    | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ----------- | ---------------------------------- | --------------------------- |
| **Batches** | object\_status                     | status                      |
|             |                                    |                             |

### Carrier Accounts

| Resource             | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| -------------------- | ---------------------------------- | --------------------------- |
| **Carrier Accounts** |                                    | carrier\_images             |
|                      |                                    | carrier\_images.300         |
|                      |                                    | carrier\_images.425         |
|                      |                                    | carrier\_name               |
|                      |                                    |                             |

### Manifests

| Resource      | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ------------- | ---------------------------------- | --------------------------- |
| **Manifests** | is\_test                           |                             |
|               | object\_status                     | status                      |
|               | submission\_date                   |                             |
|               |                                    | shipment\_date              |
|               |                                    |                             |

### Refund

| Resource   | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ---------- | ---------------------------------- | --------------------------- |
| **Refund** | object\_status                     | status                      |
|            |                                    |                             |

### Customs Declarations

| Resource                 | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ------------------------ | ---------------------------------- | --------------------------- |
| **Customs Declarations** |                                    | address\_importer           |
|                          |                                    | b13a\_filing\_option        |
|                          |                                    | b13a\_number                |
|                          |                                    | duties\_payor               |
|                          |                                    | exporter\_identification    |
|                          |                                    | invoiced\_charges           |
|                          |                                    | is\_vat\_collected          |
|                          |                                    |                             |

### Customs Items

| Resource          | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ----------------- | ---------------------------------- | --------------------------- |
| **Customs Items** |                                    | eccn\_ear9                  |
|                   |                                    |                             |

### Tracks

| Resource   | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ---------- | ---------------------------------- | --------------------------- |
| **Tracks** |                                    | tracking\_status.substatus  |
|            |                                    | substatus.text              |
|            |                                    | substatus.code              |
|            |                                    | substatus.action\_required  |
|            |                                    | description                 |
|            |                                    |                             |

### Transactions

| Resource         | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ---------------- | ---------------------------------- | --------------------------- |
| **Transactions** | customs\_note                      |                             |
|                  | notification\_email\_from          |                             |
|                  | notification\_email\_other         |                             |
|                  | notification\_email\_to            |                             |
|                  | object\_status                     | status                      |
|                  | pickup\_date                       |                             |
|                  | submission\_note                   |                             |
|                  | tracking\_history                  |                             |
|                  | was\_test                          | test                        |
|                  |                                    | billing.payments            |
|                  |                                    | billing                     |
|                  |                                    | qr\_code\_url               |
|                  |                                    |                             |

### Rates

| Resource  | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉       |
| --------- | ---------------------------------- | --------------------------------- |
| **Rates** | available\_shippo                  |                                   |
|           | days                               | estimated\_days                   |
|           | delivery\_attempts                 |                                   |
|           | inbound\_endpoint                  |                                   |
|           | insurance                          |                                   |
|           | insurance\_amount                  |                                   |
|           | insurance\_amount\_local           |                                   |
|           | insurance\_currency                |                                   |
|           | insurance\_currency\_local         |                                   |
|           | object\_purpose                    |                                   |
|           | object\_state                      |                                   |
|           | object\_updated                    |                                   |
|           | outbound\_endpoint                 |                                   |
|           | servicelevel\_name                 | servicelevel.name                 |
|           | servicelevel\_terms                | servicelevel.terms                |
|           | servicelevel\_token                | servicelevel.token                |
|           | trackable                          |                                   |
|           |                                    | servicelevel.extended\_token      |
|           |                                    | servicelevel.parent\_servicelevel |
|           |                                    | included\_insurance\_price        |
|           |                                    | servicelevel                      |
|           |                                    |                                   |

### Shipments

| Resource      | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉         |
| ------------- | ---------------------------------- | ----------------------------------- |
| **Shipments** | insurance\_amount                  |                                     |
|               | insurance\_currency                |                                     |
|               | object\_purpose                    |                                     |
|               | object\_state                      |                                     |
|               | object\_status                     |                                     |
|               | parcel                             |                                     |
|               | rates\_list                        |                                     |
|               | rates\_url                         |                                     |
|               | reference\_1                       |                                     |
|               | reference\_2                       |                                     |
|               | return\_of                         |                                     |
|               | submission\_date                   |                                     |
|               | submission\_type                   |                                     |
|               |                                    | address\_from.is\_complete          |
|               |                                    | address\_from.validation\_results   |
|               |                                    | address\_from.name                  |
|               |                                    | address\_from.street3               |
|               |                                    | address\_from.zip                   |
|               |                                    | address\_from.city                  |
|               |                                    | address\_from.state                 |
|               |                                    | address\_from.test                  |
|               |                                    | address\_from.object\_id            |
|               |                                    | status                              |
|               |                                    | address\_to.is\_complete            |
|               |                                    | address\_from.company               |
|               |                                    | address\_from.is\_residential       |
|               |                                    | address\_from.email                 |
|               |                                    | address\_from.country               |
|               |                                    | address\_from.phone                 |
|               |                                    | address\_from.street2               |
|               |                                    | address\_from.street1               |
|               |                                    | address\_from.street\_no            |
|               |                                    | address\_to.object\_id              |
|               |                                    | address\_return.city                |
|               |                                    | address\_return.company             |
|               |                                    | address\_return.country             |
|               |                                    | address\_return.email               |
|               |                                    | address\_return.is\_complete        |
|               |                                    | address\_return.is\_residential     |
|               |                                    | address\_return.name                |
|               |                                    | address\_return.object\_id          |
|               |                                    | address\_return.phone               |
|               |                                    | address\_return.state               |
|               |                                    | address\_return.street1             |
|               |                                    | address\_return.street2             |
|               |                                    | address\_return.street3             |
|               |                                    | address\_return.street\_no          |
|               |                                    | address\_return.test                |
|               |                                    | address\_return.validation\_results |
|               |                                    | address\_return.zip                 |
|               |                                    | address\_to.city                    |
|               |                                    | address\_to.company                 |
|               |                                    | address\_to.country                 |
|               |                                    | address\_to.email                   |
|               |                                    | address\_to.is\_residential         |
|               |                                    | address\_to.name                    |
|               |                                    | address\_to.phone                   |
|               |                                    | address\_to.state                   |
|               |                                    | address\_to.street1                 |
|               |                                    | address\_to.street2                 |
|               |                                    | address\_to.street3                 |
|               |                                    | address\_to.street\_no              |
|               |                                    | address\_to.test                    |
|               |                                    | address\_to.validation\_results     |
|               |                                    | address\_to.zip                     |
|               |                                    | alternate\_address\_to              |
|               |                                    | rates                               |
|               |                                    | parcels                             |
|               |                                    | shipment\_date                      |
|               |                                    |                                     |

### Addresses

| Resource      | Deprecated fields from v20161025 ◎ | Fields added in v20180208 ◉ |
| ------------- | ---------------------------------- | --------------------------- |
| **Addresses** | ip                                 |                             |
|               | messages                           |                             |
|               | object\_purpose                    |                             |
|               | object\_source                     |                             |
|               | object\_state                      |                             |
|               |                                    | is\_complete                |
|               |                                    | validation\_results         |

## Updated fields ◐

The following object fields have changed type in v20180208 since v20161025:

| Resource         | Field            | Field type in v20161025 | Field type changed to in v20180208 |
| ---------------- | ---------------- | ----------------------- | ---------------------------------- |
| **Orders**       | weight           | int                     | decimal                            |
| **Transactions** | tracking\_status | obj                     | str                                |
| **Shipments**    | address\_from    | str                     | Obj or address object id as a str  |
|                  | address\_to      | str                     | Obj or address object id as a str  |
|                  | address\_return  | str                     | Obj or address object id as a str  |


# Upgrading from v20170329 to v20180208
Source: https://docs.goshippo.com/api-concepts/api-upgrade-guides/v20170329-to-2018

Review deprecated and added fields when upgrading from Shippo API v20170329 to v20180208.

If you have already integrated with the Shippo API v20170329 and are now planning to upgrade to the latest version (v20180208), you can use this guide to identify which objects have changed between versions.

In these tables you will find the fields within each object have that have deprecated. In some cases, you can see a replacement field that has been added in v20180208.

## Deprecated ◎ and added ◉ fields

| Resource   | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉     |
| ---------- | ---------------------------------- | ------------------------------- |
| **Orders** | address\_from                      | from\_address                   |
|            | created\_at                        |                                 |
|            | hidden                             |                                 |
|            | items                              |                                 |
|            | to\_address.ip                     |                                 |
|            | to\_address.messages               |                                 |
|            | to\_address.object\_purpose        |                                 |
|            | to\_address.object\_source         |                                 |
|            | to\_address.object\_state          |                                 |
|            |                                    |                                 |
|            |                                    | placed\_at                      |
|            |                                    | test                            |
|            |                                    | to\_address.is\_complete        |
|            |                                    | to\_address.validation\_results |
|            |                                    |                                 |

### Carrier Accounts

| Resource             | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| -------------------- | ---------------------------------- | --------------------------- |
| **Carrier Accounts** |                                    | carrier\_images             |
|                      |                                    | carrier\_images.200         |
|                      |                                    | carrier\_images.75          |
|                      |                                    | carrier\_name               |
|                      |                                    |                             |

### Customs Declarations

| Resource                 | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| ------------------------ | ---------------------------------- | --------------------------- |
| **Customs Declarations** |                                    | address\_importer           |
|                          |                                    | b13a\_filing\_option        |
|                          |                                    | b13a\_number                |
|                          |                                    | duties\_payor               |
|                          |                                    | exporter\_identification    |
|                          |                                    | invoiced\_charges           |
|                          |                                    | is\_vat\_collected          |
|                          |                                    |                             |

### Customs Items

| Resource          | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| ----------------- | ---------------------------------- | --------------------------- |
| **Customs Items** |                                    | eccn\_ear9                  |
|                   |                                    |                             |

### Tracks

| Resource   | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| ---------- | ---------------------------------- | --------------------------- |
| **Tracks** |                                    | tracking\_status.substatus  |
|            |                                    | substatus.text              |
|            |                                    | substatus.code              |
|            |                                    | substatus.action\_required  |
|            |                                    | description                 |
|            |                                    |                             |

### Transactions

| Resource         | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| ---------------- | ---------------------------------- | --------------------------- |
| **Transactions** | tracking\_history                  |                             |
|                  |                                    | qr\_code\_url               |
|                  |                                    |                             |

### Rates

| Resource  | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉       |
| --------- | ---------------------------------- | --------------------------------- |
| **Rates** | days                               | estimated\_days                   |
|           |                                    | included\_insurance\_price        |
|           |                                    | servicelevel.extended\_token      |
|           |                                    |                                   |
|           |                                    | servicelevel.parent\_servicelevel |
|           |                                    |                                   |

### Shipments

| Resource      | Deprecated fields from v20170329 ◎ | Fields added in v20180208 ◉ |
| ------------- | ---------------------------------- | --------------------------- |
| **Shipments** |                                    | alternate\_address\_to      |

## Updated fields ◐

The following object fields have changed type in v20180208 since v20170329:

| Resource         | Field            | Field type in v20170329 | Field type changed to in v20180208 |
| ---------------- | ---------------- | ----------------------- | ---------------------------------- |
| **Orders**       | weight           | int                     | decimal                            |
| **Transactions** | tracking\_status | obj                     | str                                |


# Upgrading from v20170801  to v20180208
Source: https://docs.goshippo.com/api-concepts/api-upgrade-guides/v20170801-to-2018

Review the fields added when upgrading from Shippo API v20170801 to v20180208, with no deprecations.

If you have already integrated with the Shippo API v20170801 and are now planning to upgrade to the latest version (v20180208), you can use this guide to identify which objects have changed between versions.

No keys from v20170801 have been depreciated or changed type in v20180208.
The following response keys have been added in v20180208 since v20170329:

## Added ◉ fields

### Carrier Accounts

| Resource             | Fields added in v20180208 ◉ |
| -------------------- | --------------------------- |
| **Carrier Accounts** | carrier\_images             |
|                      | carrier\_images.200         |
|                      | carrier\_images.75          |
|                      | carrier\_name               |
|                      |                             |

### Customs Declarations

| Resource                 | Fields added in v20180208 ◉ |
| ------------------------ | --------------------------- |
| **Customs Declarations** | b13a\_filing\_option        |
|                          | b13a\_number                |
|                          | duties\_payor               |
|                          | exporter\_identification    |
|                          | invoiced\_charges           |
|                          | is\_vat\_collected          |
|                          |                             |

### Customs Items

| Resource          | Fields added in v20180208 ◉ |
| ----------------- | --------------------------- |
| **Customs Items** | eccn\_ear9                  |
|                   |                             |

### Tracks

| Resource   | Fields added in v20180208 ◉ |
| ---------- | --------------------------- |
| **Tracks** | description                 |
|            |                             |

### Transactions

| Resource         | Fields added in v20180208 ◉ |
| ---------------- | --------------------------- |
| **Transactions** | qr\_code\_url               |
|                  |                             |

### Rates

| Resource  | Fields added in v20180208 ◉       |
| --------- | --------------------------------- |
| **Rates** | included\_insurance\_price        |
|           | servicelevel.extended\_token      |
|           | servicelevel.parent\_servicelevel |
|           |                                   |

### Shipments

| Resource      | Fields added in v20180208 ◉ |
| ------------- | --------------------------- |
| **Shipments** | alternate\_address\_to      |


# API versions
Source: https://docs.goshippo.com/api-concepts/api-versioning

Learn how Shippo API versioning works, how to set your version, and how to test before upgrading.

The Shippo API uses versioning to roll out backwards-incompatible changes over time.

## About versioning

The API version will control the API and webhook behaviors, such as parameters accepted in requests, and response properties. Your account is automatically set to the latest version when you sign up for Shippo.

A new version of the API is released when backwards-incompatible changes are made to the API. To avoid breaking your code, we will never force you to upgrade until you're ready.

We will be releasing backwards-compatible changes without introducing new versions. Your code will be able to handle these changes no matter what version it's on.

Examples of backwards-compatible changes:

* Adding new API endpoints
* Adding new optional response attributes to an existing resource
* Adding new optional request attributes

## Release notes and communication

Backwards-incompatible changes will be documented in the [release](/api-concepts/api-change-log) as part of every version release. Documentation will provide in-depth explanations of the changes.

## Upgrade your API version

We recommend staying up-to-date with the current API version to take advantage of latest improvements to the Shippo API.

To see your current version and upgrade to the latest, visit the [Developer keys menu](https://portal.goshippo.com/api-config/api) on the Shippo Developer portal.

Versioning of the Shippo API will be released as dates, displayed as: `YYYY-MM-DD`.

You can set the version in each API call using the header parameter `Shippo-API-Version`.
If you do not set the `Shippo-API-Version`, the Shippo API will use your [default API version](/api-concepts/api-upgrade-guides/upgrade-guide#which-shippo-api-version-do-i-use-today).

## Test before upgrading

To test your code under a different API version before committing the change, you can set the API version on a specific request by setting a header with the version you are testing. The version will be set for subsequent requests until it's changed back.

Users can only upgrade their API to the latest version. Once you've upgraded your API version, you cannot roll back to an earlier version. Please make sure to test thoroughly before doing so.

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_Token>"\
      -H "Shippo-API-Version: YYYY-MM-DD"\
      -d '{ ... }'
  # now this API request uses the API version "YYYY-MM-DD"
  ```

  ```Python Python theme={null}
  import shippo
  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>", shippo_api_version='YYYY-MM-DD')
  # now all api requests will use the API version "YYYY-MM-DD"
  ```

  ```PHP PHP theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");
  Shippo::setApiVersion("YYYY-MM-DD");
  # now all subsequent requests use the API version "YYYY-MM-DD"
  ```

  ```typescript TypeScript theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>', shippoApiVersion: 'YYYY-MM-DD'});
  // now all subsequent requests use the API version "YYYY-MM-DD"
  ```

  ```Java Java theme={null}
  import com.shippo.Shippo;
  Shippo.setApiKey(<API_Token>);
  Shippo.setApiVersion("YYYY-MM-DD");
  # now all subsequent requests use the API version "YYYY-MM-DD"
  ```

  ```cs C# theme={null}
  using Shippo;
  ShippoSDK sdk = new ShippoSDK(
      apiKeyHeader: "<API_Token>",
      shippoApiVersion: "YYYY-MM-DD"
  );
  // now all subsequent requests use the API version "YYYY-MM-DD"
  ```
</CodeGroup>


# HTTP response status codes
Source: https://docs.goshippo.com/api-concepts/apihttp-status-codes

Reference guide for HTTP response status codes returned by the Shippo API, from 200 OK to 5xx errors.

| Code    | Description                                                                                                                                                                        |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200/201 | OK. Everything worked as expected.                                                                                                                                                 |
| 204     | OK. Everything worked OK but no values were returned.                                                                                                                              |
| 400     | Bad request. The request you made was not accepted. This can be due to issues including missing a required parameter.                                                              |
| 401     | Unauthorized. Occurs for issues with authentication such as you didn't provide a token or the token you provided does not exist.                                                   |
| 404     | Not found. The requested resource doesn't exist.                                                                                                                                   |
| 409     | Conflict.  There was a conflict in your request. This could be caused by things like too many concurrent calls or if you tried to create a duplicate address in your address book. |
| 422     | Unprocessable entity . Your request contained content that could not be processed by the Shippo API.                                                                               |
| 429     | Rate limit exceeded. You have made too many requests to the Shippo API. See our [rates limit guide](/api-concepts/rate-limits).                                                    |
| 5xx     | Server error. Something has gone wrong with the Shippo server.                                                                                                                     |


# Asynchronous API response handling
Source: https://docs.goshippo.com/api-concepts/asynchronus-api-call

Learn how asynchronous API responses work in Shippo and when to use sync versus async requests.

By default, the Shippo API returns rates and labels asynchronously.

We recommend to use synchronous responses for most implementations. In the current API version, you need to explicitly opt into sync responses by setting the `async` parameter in the POST body to `false`.

## What are asynchronous responses?

Asynchronous responses mean that Shippo won't be returning rates or label you have requested immediately. After your Rates or Label API POST call, you will get a successful response from the Shippo API, but without the actual rates or label. This allows your implementation to do other tasks while Shippo is retrieving your data.

Here's a sample schema for how asynchronous API responses work, in this case for Rate requests:

![Shippo async flow chart](https://shippo-static.s3.amazonaws.com/img/various/async-calls.png)

## When does it make sense to use asynchronous responses?

It takes time for Shippo to call upstream API(s), such as the USPS or FedEx API, to retrieve rates and/or label. By using asynchronous responses, your rates or label requests won't block the rest of your code, and you can proceed with other tasks in the meantime.

The best way to handle asynchronous API responses is to access the corresponding API resource (Rate or Transaction) one or multiple times after object creation. As soon as a carrier has returned a rate or label, it will be accessible in the corresponding Shippo API resource.


# Filtering
Source: https://docs.goshippo.com/api-concepts/filtering

Learn how to use query parameters to filter and paginate results from Shippo API endpoints.

When querying an endpoint to return multiple results back, you can use query string parameters to filter the results that you are getting back. Shippo currently supports a [results](#results) parameter and some [date filtering](#date-filtering) parameters (only currently supported on the Shipments endpoint).

By default, you will only get 5 results back if you do not specify a `results` query string parameter.

<Info>
  **Note**

  If you do not specify a `results` query string parameter, the Shippo API will only return a certain number of results. The default number of results is subject to change and depends on the resource you are calling. Many resources, such as shipments, transactions, and orders return 25 by default. Use a `results` query string parameter less than 200. A `results` query string parameter greater than 200 will cause your results to be truncated.
</Info>

## Results

The response will be paginated by the number specified in the `results` query string parameter. For example, for carrier accounts, by default you would only see 5 per page, with a `next` field indicating if there is another page of results. A `previous` field will give any previous pages if you're not currently looking at the first page.

## Example

URL: `https://api.goshippo.com/carrier_accounts/?results=10`

Response:

```json theme={null}
{
    "next": null,
    "previous": null,
    "results": [
        {
            "carrier": "parcelforce",
            "object_id": "bef77ddbd2a5455eba8fcd4511eef645",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippo_parcelforce_account",
            "parameters": {"expresslink_password": "******"},
            "test": true,
            "active": true,
            "is_shippo_account": true,
            "metadata":""
        },
        {
            "carrier": "usps",
            "object_id": "2da62634606540c082f3612afe95ecae",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippo_usps_account",
            "parameters": {"is_commercial": false},
            "test": true,
            "active": true,
            "is_shippo_account": true,
            "metadata": ""
        },
        {
            "carrier": "deutsche_post",
            "object_id": "595d9cb0c0e14497bf07e75ecfec6c6d",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippo_deutsche_post_account",
            "parameters": [],
            "test": true,
            "active": true,
            "is_shippo_account": true,
            "metadata": ""
        },
        {
            "carrier": "uber",
            "object_id": "fd7f11a74c8847778fe41fed06b7fdd4",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippo_uber_account",
            "parameters": [],
            "test": true,
            "active": true,
            "is_shippo_account": true,
            "metadata": ""
        },
        {
            "carrier": "dhl_express",
            "object_id": "3d05ffe6076741228dfea04385050c0d",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippo_dhlexpress_account",
            "parameters": [],
            "test": true,
            "active": true,
            "is_shippo_account": true,
            "metadata": ""
        },
        {
            "carrier": "fedex",
            "object_id": "86a7793d3788422a8169cfae9c87ed26",
            "object_owner": "shippotle@shippo.com",
            "account_id": "86753099",
            "parameters": {
                "meter": "112233445",
                "smartpost_id": 5531
            },
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": ""
        },
        {
            "carrier": "dhl_germany",
            "object_id": "0bff0a09251d478cb919ead06709d96c",
            "object_owner": "shippotle@shippo.com",
            "account_id": "2222222222",
            "parameters": {
                "default_participation_code": "01",
                "business_customer_portal_password": "pass",
                "business_customer_portal_username": "2222222222_01",
                "tracking_password": "",
                "tracking_account": ""
            },
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": ""
        },
        {
            "carrier": "fedex",
            "object_id": "8d6dbc109aaf4bb983d534f1556ddc16",
            "object_owner": "shippotle@shippo.com",
            "account_id": "86753098",
            "parameters": {
                "meter": "112233446",
                "smartpost_id": 5531
            },
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": "Test Account"
        },
        {
            "carrier": "canada_post",
            "object_id": "518402beb1f24e608af7be9d85a0f71b",
            "object_owner": "shippotle@shippo.com",
            "account_id": "3f937e0b21ef06f7",
            "parameters": {
                "payment_method": "CreditCard",
                "api_password": "secure_p@$$w0rd",
                "contract_id": null,
                "is_platform_account": true,
                "customer_number": "0086753098"
            },
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": ""
        },
        {
            "carrier": "ups",
            "object_id": "2716480a9d7b4b31837c0dacd7d481f3",
            "object_owner": "shippotle@shippo.com",
            "account_id": "shippotle",
            "parameters": {
                "cost_center": "",
                "password": "secure_p@ssw0rd",
                "account_number": "SH1PP0",
                "usps_endorsement": null,
                "surepost": ""
            },
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": ""
        }
    ]
}
```

You can see in the above response the amount of carrier accounts happen to line up with the amount we requested back, but if we requested 7 results, there would only be 7 carriers in the response with a url in the `next` field.

***

## Date filtering

When querying the [Shipments endpoint](/api-reference/shipments/list-all-shipments) you can have an additional way to filter results by limiting the date range. We expect a date formatted to the ISO 8601 standard, and you can see some example below of what that looks like. You can retrieve any 90 day range (or smaller) of shipments by using the following query string parameters:

* `object_created_gt` -- object(s) created greater than a provided date time
* `object_created_gte` -- object(s) created greater than or equal to a provided date time
* `object_created_lt` -- object(s) created less than a provided date time
* `object_created_lte` -- object(s) created less than or equal to a provided date time

Date format examples:

* `"2017-01-01"`
* `"2017-01-01T03:30:30"` or `"2017-01-01T03:30:30.5"`
* `"2017-01-01T03:30:30Z"`

## Example

URL: `https://api.goshippo.com/shipments/?results=10&object_created_gte=2017-08-01T00:00:00&object_created_lte=2017-08-31T00:00:00`

```json theme={null}
{
    "next": "https://api.goshippo.com/shipments/?object_created_gte=2017-08-01T00%3A00%3A00&object_created_lte=2017-08-31T00%3A00%3A00&results=10&page=2",
    "previous": null,
    "results": [
        {
            "address_from": {...},
            "address_return": {...},
            "address_to": {...},
            "carrier_accounts": [],
            "customs_declaration": null,
            "extra": [],
            "messages": [],
            "metadata": "",
            "object_created": "2017-08-03T23:21:20.884Z",
            "object_id": "4a310649f51f4b15aeeabb6457b50d04",
            "object_owner": "shippotle@shippo.com",
            "object_updated": "2017-08-03T23:22:28.553Z",
            "parcels": [...],
            "rates": [...],
            "shipment_date": "2017-08-03T23:22:28.553Z",
            "status": "SUCCESS",
            "test": true
        },
        {
            "address_from": {...},
            "address_return": {...},
            "address_to": {...},
            "carrier_accounts": [],
            "customs_declaration": null,
            "extra": [],
            "messages": [],
            "metadata": "",
            "object_created": "2017-08-05T21:11:46.431Z",
            "object_id": "76055268f88c46e8b337e2058bc61186",
            "object_owner": "shippotle@shippo.com",
            "object_updated": "2017-08-05T21:11:46.431Z",
            "parcels": [...],
            "rates": [...],
            "shipment_date": "2017-08-05T21:11:46.431Z",
            "status": "SUCCESS",
            "test": true
        }
    ]
}
```

<Info>
  **Note**

  The format of the `page` query parameter in the `next` and `prev` fields is subject to change and specifically may not necessarily be an integer.
</Info>

The above response includes all shipments created on or after August 1, 2017 up to and including August 31, 2017. If `object_created_gt` and `object_created_lt` were used, it would only retrieve shipments *between* those dates. You can use any combination of `object_created_gt`/`object_created_gte` and `object_created_lt`/`object_created_lte` to filter how you need. You just need to be sure that the date range is 90 days or less.


# Glossary
Source: https://docs.goshippo.com/api-concepts/glossary

Definitions of common shipping and Shippo API terms, from address validation to white-label integrations.

At Shippo, our business is shipping. Most of the terms we use are common but sometimes we'll use terms that you may not be familiar with. Other times we might use terms you are familiar with but we use them in a different context.

This guide is a collection of terms and descriptions that we use when we talk about the Shippo API.

[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [L](#l) | [M](#m) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [W](#w) | [Z](#z)

***

## A

### Address validation

One of the most common reasons why a parcel delivery fails is because an incorrect or poorly formed address is used. [Address validation](/address-api/address-validate) is a Shippo service that checks your address for errors before creating a shipping label. Where applicable, the service provides a corrected address you can use for your shipment.

### API Portal

The [Shippo API Portal](https://portal.goshippo.com) is a single control panel for API users to manage their API-based shipping operations. Users can access invoice downloads, detailed analytics, developer tools, admin functionality, team management, and more.

### Automations

Shippo has a feature that can be used within Shippo's webApp called automations which will help automate your shipping flow.

***

## B

### Batch

A [batch](/shipments/batch-label-creation) is a technique for creating multiple labels at once.

### BYOA

Bring Your Own "carrier" Account. Shippo offers the ability to connect your carrier (BYOA) or you can use one of [Shippo's carrier accounts](#shippo-carrier-account).

***

## C

### Carrier

A carrier is a company or service who delivers purchased goods to customers. Examples of carriers include USPS, DHL, and FedEx

### Customs

Customs refers to the government agency responsible for regulating the [import and export](/international-shipping/international-shipping) of goods into and out of a country.

## D

### DAP

Delivery at Place (DAP) is an [incoterm](#incoterm). It means that the seller is responsible for delivering the goods to a specified place in the buyer's country, and they cover all costs and risks associated with transporting the goods to that location. Once the goods arrive at the agreed-upon place, the buyer takes over responsibility for import duties, taxes, and further transportation.

### DDU

Delivery Duty Unpaid (DDP) is an [incoterm](#incoterm).  It means the seller is responsible for delivering the goods to a specified location in the buyer's country, but they do not cover import duties, taxes, or customs clearance. Once the goods arrive at the agreed-upon destination, the buyer is responsible for paying any import duties, taxes, and handling customs clearance.

### DDP

Delivery Duty Paid (DDP) is an [incoterm](#incoterm). It means the seller assumes maximum responsibility for the delivery of goods. The seller is responsible for all costs and risks associated with transporting the goods to the buyer's location, including import duties, taxes, and customs clearance.

### Dimensional Weight

Dimensional weight (also known as dim weight) is a measuring method in which the total size of your parcel is measured against the total weight.

***

## E

### Elements

Elements or [Shippo Shipping Elements](/shipping-elements/index) is a suite of embeddable shipping components. It is a product that you can use to add shipping directly into your website without developing the user interface or the code behind it.

***

## F

### Filtering

[Filtering](/api-concepts/filtering) is a feature of the Shippo API where you can define which results are returned from an API call.

***

## G

### Gray label

A gray label integration is how we describe a platform integration where users have their own Shippo accounts. The platform uses their user's Shippo account to create and manage shipments.
Gray label integrations are often described alongside [white label](#white-label) integrations.

***

## H

### HS Code

Harmonized System Code (HS Code) is a standardized classification used to identify products in international trade. It is required by all carriers for international shipping. The term is often used interchangeably with tariff number.

### Hazmat

Hazmat is hazardous or dangerous materials. In shipping there are special requirements when [shipping hazmat materials](/shipments/hazmat).

***

## I

### Instalabel

Insatlabel is a feature of the Shippo API where the API can be configured to purchase a label with a [single API call](/guides/single-call) instead of the more common two label call.

### Incoterm

Incoterms are a set of internationally recognized trade terms that define the responsibilities of buyers and sellers in international trade transactions. They define things like who is responsible for delivery and transport, export and import clearance, and any associated tariffs.

### Insurance

[Shipping insurance](/shipments/shipping-insurance) is a service that provides coverage for goods while they are in transit, protecting against potential losses or damages that might occur during shipping. This type of insurance can be purchased by either the seller or the buyer, depending on the terms of the transaction, and is typically offered by shipping carriers, third-party insurers, or logistics companies.

***

## J

### JWT

JSON Web Token (JWT) is a URL-safe token used for securely transmitting information between parties as a JSON object. For your client-side applications, we recommend using a [JWT to securely authenticate](/guides/authentication-using-jwt).

***

## L

### Label

A shipping label is a document, usually affixed to your parcel, that contains all the information needed to get a parcel from its source to its destination.
Some of the information can include information such as, destination address, parcel contents, service level, tracking details, and special instructions.
A new label must be created for each shipment.

***

## M

### Manifest

[Manifests and USPS SCAN forms](/manifests-and-pickups/manifest-and-scan-forms) allow merchants to create a single piece of paper they can hand to the carrier at pickup time. The manifest has a list of all the parcels the carrier is going to be picking up that day and greatly speeds up the process of the carrier accepting each of the day's parcels.

### Metadata

Metadata is freeform text that can be used with some Shippo API objects. Metadata can be used in numerous different ways to help interact with Shippo API data.

### Multi-piece

Shipments with multiple parcels sent to the same destination can be grouped together in a multi-piece shipment to save money.

***

## O

### OAuth

Open Authorization (OAuth) is a standard for access delegation. In the Shippo API, it's commonly used for [gray label](#gray-label) integrations.

### Object ID

In the Shippo API, [objects](/api-concepts/api-objects) are used to store information. Objects can store information like addresses, shipments, and rates. Each object has an associated object ID. Each object ID is unique and you can use the object ID to reference and use the data in the object.

### Orders

An [order](/orders/orders) is the act of a customer agreeing to purchase goods from a merchant. The Shippo API includes the order endpoints The orders endpoint allows you to load orders from your system to the Shippo dashboard and to create, retrieve, list, and manage orders programmatically.

### Outbound label

An outbound label is a label that is generated for sending a parcel from the sender (merchant) to the recipient (customer). This is not the same as a [return label](#return).

***

## P

### Parcel

A parcel is an item to be shipped.

### Platform account

Shippo Platform accounts a special kind of account that enables you to control other Shippo accounts, known as Managed Shippo Accounts. This is a popular solution for many applications including marketplaces that support merchants.

### Pickup

Pickup refers to a service where a carrier collects a parcel directly from the sender's location for delivery to the recipient.

### Portal

See [Shippo API Portal](#api-portal)

***

## Q

### QR code

Quick Response (QR) code is a type of barcode that can be scanned using a smartphone or a QR code reader to quickly access information. QR codes are becoming more common in shipping. For example, some carriers provide a service where a user can use a QR to print a shipping label at parcel drop-off location.

***

## R

### Rate

Rates are the cost and service levels associated with a shipment.  Each Rate returned will have an object ID to identify each unique rate.

### Return

A return is when a shipped item is sent back from the recipient to the original sender.

### Rate shopping

[Rate shopping](/shipments/rate-shopping-with-carriers) is the practice of comparing costs and services levels of different shipping options to find the option that works best for your shipment.

***

## S

### SDK

A Software Development Kit (SDK), is a collection of tools, libraries, documentation, and code samples that developers use to create applications for specific platforms. Shippo provides [SDKs](/guides/client-libraries) in a number of languages to support our developer community.

### Shipping

Shipping is the act of transporting goods from a sender to a recipient.

### Shipment

A shipment object in the Shippo API represents a package that you intend to ship. It includes details about the sender, recipient, package dimensions, weight, and other attributes necessary for shipping.
The shipment is used to request rates from shipping carriers. Each Shipment is identified by an object ID.

### Shippo carrier account

Shippo carrier accounts are accounts that Shippo owns. You get access to these carrier accounts when you log into your shippo account. Using Shippo carrier accounts you can purchase labels immediately, without creating your own account with a carrier. The cost to purchase labels is billed through your Shippo account. Using Shippo carrier accounts you can benefit from discounts negotiated by Shippo.

### Service level

Shipping service levels refer to the various options provided by carriers that define the speed, cost, and delivery terms of shipping parcels.

***

## T

### Tracking number

A tracking number is a unique identifying number that you can use to show the location of your parcel.

### Test token

Shippo uses API tokens to authenticate your access to the Shippo API. Shippo has two types of tokens. A live token and a [test token](/guides/testing). Use your test token when you are developing and testing your integration. Using a test token means you will not incur charges.

You can use live tokens and test tokens interchangeably. This means you can develop your integration using your test token. When you are ready for production, the only change needed is to replace your test token with your live token.

### Tariff number

Often used interchangeably with [HS Code](#hs-code), is a standardized classification used to identify products in international trade.

### Transaction

A transaction is the purchase of a shipping label from a shipping provider for a specific service. You can print purchased labels and use them to ship a parcel with a carrier, such as USPS or FedEx. For each transaction, there is an object ID associated with it.

***

## W

### Webhook

A [webhook](/tracking/webhooks) is a way for one application to send real-time data or notifications to another application over the web. Webhooks allow systems to communicate with each other by delivering updates or events automatically, without the need for constant polling or manual intervention.

### White label

Similar to [gray label](#gray-label), a white label integration is how we describe a platform integration where users do not have their Shippo accounts. A white label or unbranded integration means you provide shipping to your users, but they don't see that it is enabled by another party.
A white label integration can be supported through a single Shippo account or through a [Platform account](#platform-account).
Shippo will charge you for all the shipments processed through this account.

### Web app

The [Shippo web app](https://www.goshippo.com) is the web interface for Shippo. You can use the web app to manage all your shipping needs directly from a browser. The web app includes a large number of features including order management and label creation.

***

## Z

### ZPL

Zebra Programming Language (ZPL) is a specialized language used for designing and generating labels on Zebra printers, which are commonly used for [printing shipping labels](/shipments/shipping-label-sizes).


# IP addresses and domains
Source: https://docs.goshippo.com/api-concepts/ip-addresses-and-domains

Find the domain names and IP addresses you need to allowlist for your Shippo API integration.

<Info>
  **note**

  On April 8th 2024, we are updating our IPs for the Shippo API domains.

  Under most circumstances, this will have no impact on you and your merchants and no changes are required by you.

  In a small number of cases, if custom traffic filters have been created by your team for Shippo API access, they will need to be updated before this date. If you have applied custom traffic filters, API calls to Shippo may fail if the new IP range is not allowed.

  To test if you may be impacted by this change, run the following command from your network.

  ```shell theme={null}
  curl -o /dev/null -s -w "%{http_code}\n" https://goshippo.com
  ```

  If `200` response is returned, no further action is required. If any other response is returned, you may need to update your custom traffic filters.

  Refer to the [IP Addresses](#ip-addresses) section for the list of updated IP addresses.
</Info>

## Domain names

For your integration to work with the Shippo API, it must be able to communicate with our qualified domain names. Depending on how your integration operates, you may need to add them to an allowlist.
The following list of domain names may be used to communicate with the Shippo API.

```
api.goshippo.com
platform-api.goshippo.com
```

## IP addresses

The IP addresses that the Shippo API may resolve to are listed in the [Cloudflare IP Ranges guide](https://www.cloudflare.com/en-gb/ips/).

## Webhook IP addresses

Refer to our [Webhook security guide](/tracking/webhook-security) for details on IP addresses used by our webhooks.


# Rate limits
Source: https://docs.goshippo.com/api-concepts/rate-limits

View per-endpoint rate limits for the Shippo API and learn what to do if you need higher limits.

Shippo has different rate limits depending on the endpoint and the HTTP verb that is being used (GET, POST, PUT, etc...). Below are the different rate limits defined within Shippo.

**All listed rate limits are per minute. Exceeding the rate limit will give a `429` error.**

## Limits

| **Endpoint**        | POST PUT Live / Test | GET(single) Live / Test | GET(multiple) Live / Test | PUT Live / Test |
| ------------------- | -------------------- | ----------------------- | ------------------------- | --------------- |
| Address             | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Parcel              | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Shipment            | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Rate                | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Transaction         | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Customs Item        | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Customs Declaration | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Refund              | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Manifest            | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Carrier Account     | 500 / 50             | 4000 / 400              | 50 / 10                   | 500 / 50        |
| Batch               | 50 / 10              | 400 / 40                | 50 / 10                   | --              |
| Tracking            | 750 / 50             | 500 / 50                | --                        | --              |

## GET Single vs GET Multiple

* GET **Single** -- `https://api.goshippo.com/endpoint/:object_id` request a specific object from that endpoint using the object's `object_id`.
* GET **Multiple** -- `https://api.goshippo.com/endpoint/` request a list of objects from a given endpoint. See our [Filtering tutorial](/api-concepts/filtering) for details on returning specific results.

## Need higher limits?

[Contact us](https://goshippo.com/contact/sales/) if you require higher rate limits than those found above.


# Create a new address
Source: https://docs.goshippo.com/api-reference/address-book/create-a-new-address

/api-reference/addressesapi/address_v2.yaml post /v2/addresses
Stores a new address to your address book



# Delete an address
Source: https://docs.goshippo.com/api-reference/address-book/delete-an-address

/api-reference/addressesapi/address_v2.yaml delete /v2/addresses/{address_id}
Removes an existing address from your address book using an object ID



# Retrieve a single address
Source: https://docs.goshippo.com/api-reference/address-book/retrieve-a-single-address

/api-reference/addressesapi/address_v2.yaml get /v2/addresses/{address_id}
Returns an existing address using an object ID



# Retrieve addresses
Source: https://docs.goshippo.com/api-reference/address-book/retrieve-addresses

/api-reference/addressesapi/address_v2.yaml get /v2/addresses
Returns a list of addresses based on search criteria



# Update an address
Source: https://docs.goshippo.com/api-reference/address-book/update-an-address

/api-reference/addressesapi/address_v2.yaml put /v2/addresses/{address_id}
Updates values in an existing address



# Create a new address
Source: https://docs.goshippo.com/api-reference/addresses/create-a-new-address

/spec/shippoapi/public-api.yaml post /addresses
Creates a new address object. You can use address objects to create new shipments, calculate rates, and to create orders.



# List all addresses
Source: https://docs.goshippo.com/api-reference/addresses/list-all-addresses

/spec/shippoapi/public-api.yaml get /addresses
Returns a list of all address objects that have been created in this account.



# Retrieve an address
Source: https://docs.goshippo.com/api-reference/addresses/retrieve-an-address

/spec/shippoapi/public-api.yaml get /addresses/{AddressId}
Returns an existing address using an object ID.



# Validate an address
Source: https://docs.goshippo.com/api-reference/addresses/validate-an-address

/spec/shippoapi/public-api.yaml get /addresses/{AddressId}/validate
Validates an existing address using an object ID



# Batch
Source: https://docs.goshippo.com/api-reference/batch

/spec/shippoapi/public-api.yaml webhook batch



# Add shipments to a batch
Source: https://docs.goshippo.com/api-reference/batches/add-shipments-to-a-batch

/spec/shippoapi/public-api.yaml post /batches/{BatchId}/add_shipments
Adds batch shipments to an existing batch.



# Create a batch
Source: https://docs.goshippo.com/api-reference/batches/create-a-batch

/spec/shippoapi/public-api.yaml post /batches
Creates a new batch object for purchasing shipping labels for many shipments at once. Batches are created asynchronously. This means that the API response won't include your batch shipments yet. You need to retrieve the batch later to verify that all batch shipments are valid.



# Purchase a batch
Source: https://docs.goshippo.com/api-reference/batches/purchase-a-batch

/spec/shippoapi/public-api.yaml post /batches/{BatchId}/purchase
Purchases an existing batch with a status of `VALID`. 
Once you send a POST request to the purchase endpoint the batch status will change to `PURCHASING`. 
When all the shipments are purchased, the status will change to `PURCHASED` and you will receive a 
`batch_purchased` webhook indicating that the batch has been purchased



# Remove shipments from a batch
Source: https://docs.goshippo.com/api-reference/batches/remove-shipments-from-a-batch

/spec/shippoapi/public-api.yaml post /batches/{BatchId}/remove_shipments
Removes shipments from an existing batch shipment.



# Retrieve a batch
Source: https://docs.goshippo.com/api-reference/batches/retrieve-a-batch

/spec/shippoapi/public-api.yaml get /batches/{BatchId}
Returns a batch using an object ID.

Batch shipments are displayed 100 at a time. You can iterate through each page using the `?page=` query parameter. You can also filter based on batch shipment status, for example, by passing a query param like `?object_results=creation_failed`.

For more details on filtering results, see our guide on [filtering](https://docs.goshippo.com/docs/api_concepts/filtering/).



# Add a Shippo carrier account
Source: https://docs.goshippo.com/api-reference/carrier-accounts/add-a-shippo-carrier-account

/spec/shippoapi/public-api.yaml post /carrier_accounts/register/new
Adds a Shippo carrier account



# Connect an existing carrier account using OAuth 2.0
Source: https://docs.goshippo.com/api-reference/carrier-accounts/connect-an-existing-carrier-account-using-oauth-20

/spec/shippoapi/public-api.yaml get /carrier_accounts/{CarrierAccountObjectId}/signin/initiate
Used by client applications to setup or reconnect an existing carrier account with carriers that support OAuth 2.0



# Create a new carrier account
Source: https://docs.goshippo.com/api-reference/carrier-accounts/create-a-new-carrier-account

/spec/shippoapi/public-api.yaml post /carrier_accounts
Creates a new carrier account or connects an existing carrier account to the Shippo account.



# Get Carrier Registration status
Source: https://docs.goshippo.com/api-reference/carrier-accounts/get-carrier-registration-status

/spec/shippoapi/public-api.yaml get /carrier_accounts/reg-status
Returns the registration status for the given account for the given carrier



# List all carrier accounts
Source: https://docs.goshippo.com/api-reference/carrier-accounts/list-all-carrier-accounts

/spec/shippoapi/public-api.yaml get /carrier_accounts
Returns a list of all carrier accounts connected to your Shippo account. These carrier accounts include both Shippo carrier accounts and your own carrier accounts that you have connected to your Shippo account.

Additionally, you can get information about the service levels associated with each carrier account by passing in the `?service_levels=true` query parameter.
Using it appends the property `service_levels` to each carrier account.
By default, if the query parameter is omitted, the `service_levels` property will not be included in the response.



# Retrieve a carrier account
Source: https://docs.goshippo.com/api-reference/carrier-accounts/retrieve-a-carrier-account

/spec/shippoapi/public-api.yaml get /carrier_accounts/{CarrierAccountId}
Returns an existing carrier account using an object ID.



# Update a carrier account
Source: https://docs.goshippo.com/api-reference/carrier-accounts/update-a-carrier-account

/spec/shippoapi/public-api.yaml put /carrier_accounts/{CarrierAccountId}
Updates an existing carrier account object. The account_id and carrier can't be updated. This is because they form the unique identifier together.



# List all carrier parcel templates
Source: https://docs.goshippo.com/api-reference/carrier-parcel-templates/list-all-carrier-parcel-templates

/spec/shippoapi/public-api.yaml get /parcel-templates
List all carrier parcel template objects.

Use the following query string params to filter the results as needed:

- `include=all` (the default): includes templates from all carriers
- `include=user`: includes templates only from carriers which the user has added (whether or not they're currently enabled)
- `include=enabled`: includes templates only for carriers which the user has added and enabled
- `carrier=<token>`: filter by specific carrier, e.g. `fedex`, `usps`



# Retrieve a carrier parcel templates
Source: https://docs.goshippo.com/api-reference/carrier-parcel-templates/retrieve-a-carrier-parcel-templates

/spec/shippoapi/public-api.yaml get /parcel-templates/{CarrierParcelTemplateToken}
Fetches the parcel template information for a specific carrier parcel template, identified by the token.



# Create a new customs declaration
Source: https://docs.goshippo.com/api-reference/customs-declarations/create-a-new-customs-declaration

/spec/shippoapi/public-api.yaml post /customs/declarations
Creates a new customs declaration object



# List all customs declarations
Source: https://docs.goshippo.com/api-reference/customs-declarations/list-all-customs-declarations

/spec/shippoapi/public-api.yaml get /customs/declarations
Returns a list of all customs declaration objects



# Retrieve a customs declaration
Source: https://docs.goshippo.com/api-reference/customs-declarations/retrieve-a-customs-declaration

/spec/shippoapi/public-api.yaml get /customs/declarations/{CustomsDeclarationId}
Returns an existing customs declaration using an object ID



# Create a new customs item
Source: https://docs.goshippo.com/api-reference/customs-items/create-a-new-customs-item

/spec/shippoapi/public-api.yaml post /customs/items
Creates a new customs item object.



# List all customs items
Source: https://docs.goshippo.com/api-reference/customs-items/list-all-customs-items

/spec/shippoapi/public-api.yaml get /customs/items
Returns a list all customs items objects.



# Retrieve a customs item
Source: https://docs.goshippo.com/api-reference/customs-items/retrieve-a-customs-item

/spec/shippoapi/public-api.yaml get /customs/items/{CustomsItemId}
Returns an existing customs item using an object ID



# Create a new manifest
Source: https://docs.goshippo.com/api-reference/manifests/create-a-new-manifest

/spec/shippoapi/public-api.yaml post /manifests
Creates a new manifest object.



# List all manifests
Source: https://docs.goshippo.com/api-reference/manifests/list-all-manifests

/spec/shippoapi/public-api.yaml get /manifests
Returns a list of all manifest objects.



# Retrieve a manifest
Source: https://docs.goshippo.com/api-reference/manifests/retrieve-a-manifest

/spec/shippoapi/public-api.yaml get /manifests/{ManifestId}
Returns an existing manifest using an object ID.



# Create a new order
Source: https://docs.goshippo.com/api-reference/orders/create-a-new-order

/spec/shippoapi/public-api.yaml post /orders
Creates a new order object.



# List all orders
Source: https://docs.goshippo.com/api-reference/orders/list-all-orders

/spec/shippoapi/public-api.yaml get /orders
Returns a list of all order objects.



# Retrieve an order
Source: https://docs.goshippo.com/api-reference/orders/retrieve-an-order

/spec/shippoapi/public-api.yaml get /orders/{OrderId}
Retrieves an existing order using an object ID.



# API Reference Overview
Source: https://docs.goshippo.com/api-reference/overview

Learn about the Shippo API — authentication, request format, versioning, and core REST principles.

<Info>
  First-time users and those looking for specific integration tutorials, see our [full API documentation and guides](/guides/api-quickstart).

  Download the [API Specification yaml file](/spec/shippoapi/public-api.yaml).
</Info>

## API Resources

All API URLs listed in this documentation are relative to **[https://api.goshippo.com/](https://api.goshippo.com/)**.

For example, the `/addresses/` resource is reachable at `https://api.goshippo.com/addresses/`.

## Authentication

The API requires Shippo's token HTTP Authentication with your Shippo token (live or test).

In order to authenticate properly, put `Authorization: ShippoToken <token>` in your request header. You can find your token on the [Shippo API settings page](https://goshippo.com/user/apikeys/).

For more information about authentication and test mode, see our [Authentication guide](/guides/authentication).

The API is available via Secure Socket Layer (SSL) only. All requests to the Shippo API must use TLS version 1.2 or higher.

## Request & Response Data

Request data is passed to the API by **POSTing JSON objects** with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource.

Response data is also formatted as a JSON object. You can specify how many results per page are to be returned. For instance, `/rates/?results=25` will return up to 25 results.

## REST & Disposable Objects

The Shippo API is built around [REST principles](http://en.wikipedia.org/wiki/Representational_State_Transfer). Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Only the Carrier Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates, Transactions, Refunds, Customs Items, and Customs Declarations are disposable. This means that once you have created an object, you cannot change it. Instead, create a new one with the desired values.

## API Version

This reference guide supports the Shippo API version: `2018-02-08`.

To see reference guides for older API versions, see our [legacy reference guide](/guides/legacy-reference). For more information about Shippo API versions, see our [API versions guide](/api-concepts/api-versioning).


# Parcel Templates
Source: https://docs.goshippo.com/api-reference/parcel-templates/index

Predefined parcel templates with preset dimensions for supported carriers. Use these tokens when creating parcels.

<CardGroup>
  <Card title="Aramex Australia" href="/api-reference/parcel-templates/aramex-australia" />

  <Card title="DHL eCommerce" href="/api-reference/parcel-templates/dhl-ecommerce" />

  <Card title="DPD UK" href="/api-reference/parcel-templates/dpd-uk" />

  <Card title="FedEx" href="/api-reference/parcel-templates/fedex" />

  <Card title="UPS" href="/api-reference/parcel-templates/ups" />

  <Card title="USPS" href="/api-reference/parcel-templates/usps" />
</CardGroup>


# Create a new parcel
Source: https://docs.goshippo.com/api-reference/parcels/create-a-new-parcel

/spec/shippoapi/public-api.yaml post /parcels
Creates a new parcel object.



# List all parcels
Source: https://docs.goshippo.com/api-reference/parcels/list-all-parcels

/spec/shippoapi/public-api.yaml get /parcels
Returns a list of all parcel objects.



# Retrieve an existing parcel
Source: https://docs.goshippo.com/api-reference/parcels/retrieve-an-existing-parcel

/spec/shippoapi/public-api.yaml get /parcels/{ParcelId}
Returns parcel details using an existing parcel object ID (this will not return parcel details associated with un-purchased shipment/rate parcel object IDs).



# Parse Address
Source: https://docs.goshippo.com/api-reference/parser/parse-address

/api-reference/addressesapi/address_v2.yaml get /v2/addresses/parse
Parses a single string into an Address model



# Create a pickup
Source: https://docs.goshippo.com/api-reference/pickups/create-a-pickup

/spec/shippoapi/public-api.yaml post /pickups
Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping.



# Clear current default parcel template
Source: https://docs.goshippo.com/api-reference/rates-at-checkout/clear-current-default-parcel-template

/spec/shippoapi/public-api.yaml delete /live-rates/settings/parcel-template
Clears the currently configured default parcel template for live rates.



# Generate a live rates request
Source: https://docs.goshippo.com/api-reference/rates-at-checkout/generate-a-live-rates-request

/spec/shippoapi/public-api.yaml post /live-rates
Initiates a live rates request. Include either the object ID for
an existing address record or a fully formed address object when entering
an address value. You can also enter the object ID of an existing user parcel
template or a fully formed user parcel template object as the parcel value.



# Show current default parcel template
Source: https://docs.goshippo.com/api-reference/rates-at-checkout/show-current-default-parcel-template

/spec/shippoapi/public-api.yaml get /live-rates/settings/parcel-template
Retrieve and display the currently configured default parcel template for live rates.



# Update default parcel template
Source: https://docs.goshippo.com/api-reference/rates-at-checkout/update-default-parcel-template

/spec/shippoapi/public-api.yaml put /live-rates/settings/parcel-template
Update the currently configured default parcel template for live rates. The object_id in the request payload should identify the user parcel template to be the new default.



# Retrieve a rate
Source: https://docs.goshippo.com/api-reference/rates/retrieve-a-rate

/spec/shippoapi/public-api.yaml get /rates/{RateId}
Returns an existing rate using a rate object ID. Rates older than 390 days are not returned.



# Retrieve shipment rates
Source: https://docs.goshippo.com/api-reference/rates/retrieve-shipment-rates

/spec/shippoapi/public-api.yaml get /shipments/{ShipmentId}/rates
Returns a paginated list of rates associated with a shipment. Rates for shipments older than 390 days are not returned.



# Retrieve shipment rates in currency
Source: https://docs.goshippo.com/api-reference/rates/retrieve-shipment-rates-in-currency

/spec/shippoapi/public-api.yaml get /shipments/{ShipmentId}/rates/{CurrencyCode}
Returns all available shipping rates for a shipment object.

When you create a new valid shipment object, Shippo automatically calculates all available rates. Depending on your shipment data, there may be none, one or multiple rates.

By default, the calculated rates will return the price in two currencies under the `amount` and `amount_local` keys, respectively. The `amount` key will contain the price of a rate expressed in the currency that is used in the country from where the parcel originates, and the `amount_local` key will contain the price expressed in the currency that is used in the country the parcel is shipped to. You can request rates with prices expressed in a different currency by adding the currency code to the end of the resource URL. The full list of supported currencies along with their codes can be viewed on [open exchange rates](http://openexchangerates.org/api/currencies.json).

Note: re-requesting the rates with a different currency code will re-queue the shipment (i.e. set the Shipment's `status` to `QUEUED`) and the converted currency rates will only be available when the Shipment's `status` is set to `SUCCESS`.

Rates for shipments older than 390 days are not returned.



# Create a refund
Source: https://docs.goshippo.com/api-reference/refunds/create-a-refund

/spec/shippoapi/public-api.yaml post /refunds
Creates a new refund object.



# List all refunds
Source: https://docs.goshippo.com/api-reference/refunds/list-all-refunds

/spec/shippoapi/public-api.yaml get /refunds/
Returns a list all refund objects.



# Retrieve a refund
Source: https://docs.goshippo.com/api-reference/refunds/retrieve-a-refund

/spec/shippoapi/public-api.yaml get /refunds/{RefundId}
Returns an existing rate using a rate object ID.



# Create a new service group
Source: https://docs.goshippo.com/api-reference/service-groups/create-a-new-service-group

/spec/shippoapi/public-api.yaml post /service-groups
Creates a new service group.



# Delete a service group
Source: https://docs.goshippo.com/api-reference/service-groups/delete-a-service-group

/spec/shippoapi/public-api.yaml delete /service-groups/{ServiceGroupId}
Deletes an existing service group using an object ID.



# List all service groups
Source: https://docs.goshippo.com/api-reference/service-groups/list-all-service-groups

/spec/shippoapi/public-api.yaml get /service-groups
Returns a list of service group objects.



# Update an existing service group
Source: https://docs.goshippo.com/api-reference/service-groups/update-an-existing-service-group

/spec/shippoapi/public-api.yaml put /service-groups
Updates an existing service group object. The object_id cannot be updated as it is the unique identifier for the object.



# Service Levels
Source: https://docs.goshippo.com/api-reference/service-levels/index

Service level tokens for all supported carriers. Use these tokens when creating shipments, transactions, and rates.

<CardGroup>
  <Card title="Airterra" href="/api-reference/service-levels/airterra" />

  <Card title="APC Postal" href="/api-reference/service-levels/apc-postal" />

  <Card title="APG" href="/api-reference/service-levels/apg" />

  <Card title="Aramex" href="/api-reference/service-levels/fastway-australia" />

  <Card title="Asendia US" href="/api-reference/service-levels/asendia-us" />

  <Card title="Australia Post" href="/api-reference/service-levels/australia-post" />

  <Card title="BetterTrucks" href="/api-reference/service-levels/better-trucks" />

  <Card title="Canada Post" href="/api-reference/service-levels/canada-post" />

  <Card title="Chronopost" href="/api-reference/service-levels/chronopost" />

  <Card title="Colissimo" href="/api-reference/service-levels/colissimo" />

  <Card title="Correos España" href="/api-reference/service-levels/correos-espana" />

  <Card title="Deutsche Post" href="/api-reference/service-levels/deutsche-post" />

  <Card title="DHL eCommerce" href="/api-reference/service-levels/dhl-ecommerce" />

  <Card title="DHL Express" href="/api-reference/service-levels/dhl-express" />

  <Card title="DHL Germany" href="/api-reference/service-levels/dhl-germany" />

  <Card title="DPD GERMANY" href="/api-reference/service-levels/dpd-de" />

  <Card title="DPD UK" href="/api-reference/service-levels/dpd-uk" />

  <Card title="ePost Global" href="/api-reference/service-levels/rr-donnelley" />

  <Card title="Evri UK" href="/api-reference/service-levels/hermes-uk" />

  <Card title="FedEx" href="/api-reference/service-levels/fedex" />

  <Card title="Globegistics" href="/api-reference/service-levels/globegistics" />

  <Card title="GLS US" href="/api-reference/service-levels/gls-us" />

  <Card title="Jitsu" href="/api-reference/service-levels/axlehire" />

  <Card title="LaserShip" href="/api-reference/service-levels/lasership" />

  <Card title="LSO" href="/api-reference/service-levels/lso" />

  <Card title="Mondial Relay" href="/api-reference/service-levels/mondial-relay" />

  <Card title="OnTrac" href="/api-reference/service-levels/ontrac" />

  <Card title="Parcelforce" href="/api-reference/service-levels/parcelforce" />

  <Card title="Poste Italiane" href="/api-reference/service-levels/poste-italiane" />

  <Card title="Purolator" href="/api-reference/service-levels/purolator" />

  <Card title="Royal Mail" href="/api-reference/service-levels/royal-mail" />

  <Card title="Royal Mail Storefeeder" href="/api-reference/service-levels/royal-mail-sf" />

  <Card title="Swyft" href="/api-reference/service-levels/swyft" />

  <Card title="UDS" href="/api-reference/service-levels/uds" />

  <Card title="UPS" href="/api-reference/service-levels/ups" />

  <Card title="USPS" href="/api-reference/service-levels/usps" />

  <Card title="Veho" href="/api-reference/service-levels/veho" />
</CardGroup>


# Create a new shipment
Source: https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment

/spec/shippoapi/public-api.yaml post /shipments
Creates a new shipment object.



# List all shipments
Source: https://docs.goshippo.com/api-reference/shipments/list-all-shipments

/spec/shippoapi/public-api.yaml get /shipments
Returns a list of all shipment objects.

To filter results, use the optional query parameters below. Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).

- `object_created_gt`: object(s) created after the provided date time
- `object_created_gte`: object(s) created at or after the provided date time
- `object_created_lt`: object(s) created before the provided date time
- `object_created_lte`: object(s) created at or before the provided date time

Date format examples: `2017-01-01`, `2017-01-01T03:30:30` (or `2017-01-01T03:30:30.5`), `2017-01-01T03:30:30Z`

Example URL: `https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30`

Note: Shipment objects older than 390 days are not returned.



# Retrieve a shipment
Source: https://docs.goshippo.com/api-reference/shipments/retrieve-a-shipment

/spec/shippoapi/public-api.yaml get /shipments/{ShipmentId}
Returns an existing shipment using an object ID. Shipment objects older than 390 days are not returned.



# Create a Shippo Account
Source: https://docs.goshippo.com/api-reference/shippo-accounts/create-a-shippo-account

/spec/shippoapi/public-api.yaml post /shippo-accounts
Creates a new [Shippo Managed Account](https://docs.goshippo.com/docs/platformaccounts/platform_using_accounts/).



# List all Shippo Accounts
Source: https://docs.goshippo.com/api-reference/shippo-accounts/list-all-shippo-accounts

/spec/shippoapi/public-api.yaml get /shippo-accounts
Returns a list of Shippo Managed Accounts objects.



# Retrieve a Shippo Account
Source: https://docs.goshippo.com/api-reference/shippo-accounts/retrieve-a-shippo-account

/spec/shippoapi/public-api.yaml get /shippo-accounts/{ShippoAccountId}
Returns a Shippo Managed Account using an object ID.



# Update a Shippo Account
Source: https://docs.goshippo.com/api-reference/shippo-accounts/update-a-shippo-account

/spec/shippoapi/public-api.yaml put /shippo-accounts/{ShippoAccountId}
Updates a Shippo Managed Account using an object ID.



# Track
Source: https://docs.goshippo.com/api-reference/track

/spec/shippoapi/public-api.yaml webhook track



# Get a tracking status
Source: https://docs.goshippo.com/api-reference/tracking-status/get-a-tracking-status

/spec/shippoapi/public-api.yaml get /tracks/{Carrier}/{TrackingNumber}
Returns the tracking status of a shipment using a carrier name and a tracking number.



# Register a tracking webhook
Source: https://docs.goshippo.com/api-reference/tracking-status/register-a-tracking-webhook

/spec/shippoapi/public-api.yaml post /tracks
Registers a webhook that will send HTTP notifications to you when the status of your tracked package changes. For more details on creating a webhook, see our guides on [Webhooks](https://docs.goshippo.com/docs/tracking/webhooks/) and [Tracking](https://docs.goshippo.com/docs/tracking/tracking/).



# Transaction
Source: https://docs.goshippo.com/api-reference/transaction

/spec/shippoapi/public-api.yaml webhook transaction



# Create a shipping label
Source: https://docs.goshippo.com/api-reference/transactions/create-a-shipping-label

/spec/shippoapi/public-api.yaml post /transactions
Creates a new transaction object and purchases the shipping label using a rate object that has previously been created.

Alternatively, creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token.



# List all shipping labels
Source: https://docs.goshippo.com/api-reference/transactions/list-all-shipping-labels

/spec/shippoapi/public-api.yaml get /transactions
Returns a list of all transaction objects.



# Retrieve a shipping label
Source: https://docs.goshippo.com/api-reference/transactions/retrieve-a-shipping-label

/spec/shippoapi/public-api.yaml get /transactions/{TransactionId}
Returns an existing transaction using an object ID.



# Create a new user parcel template
Source: https://docs.goshippo.com/api-reference/user-parcel-templates/create-a-new-user-parcel-template

/spec/shippoapi/public-api.yaml post /user-parcel-templates
Creates a new user parcel template.

You can choose to create a
parcel template using a preset carrier template as a starting point, or
you can create an entirely custom one. To use a preset carrier template,
pass in a unique template token from [this list](/shippoapi/public-api/parcel-templates)
plus the weight fields (**weight** and **weight_unit**). Otherwise, omit
the template field and pass the other fields, for the weight, length, height,
and depth, as well as their units."



# Delete a user parcel template
Source: https://docs.goshippo.com/api-reference/user-parcel-templates/delete-a-user-parcel-template

/spec/shippoapi/public-api.yaml delete /user-parcel-templates/{UserParcelTemplateObjectId}
Deletes a user parcel template using an object ID.



# List all user parcel templates
Source: https://docs.goshippo.com/api-reference/user-parcel-templates/list-all-user-parcel-templates

/spec/shippoapi/public-api.yaml get /user-parcel-templates
Returns a list all of all user parcel template objects.



# Retrieves a user parcel template
Source: https://docs.goshippo.com/api-reference/user-parcel-templates/retrieves-a-user-parcel-template

/spec/shippoapi/public-api.yaml get /user-parcel-templates/{UserParcelTemplateObjectId}
Returns the parcel template information for a specific user parcel
template, identified by the object ID.



# Update an existing user parcel template
Source: https://docs.goshippo.com/api-reference/user-parcel-templates/update-an-existing-user-parcel-template

/spec/shippoapi/public-api.yaml put /user-parcel-templates/{UserParcelTemplateObjectId}
Updates an existing user parcel template.



# Validate address
Source: https://docs.goshippo.com/api-reference/validation/validate-address

/api-reference/addressesapi/address_v2.yaml get /v2/addresses/validate
Returns validation test results along with a recommended address. Validates both US and international addresses.

**US required combinations**

- state_province + city_locality + address_line_1
- or address_line_1 + postal_code

**International required combinations**

- city_locality + address_line_1



# Create a new webhook
Source: https://docs.goshippo.com/api-reference/webhooks/create-a-new-webhook

/spec/shippoapi/public-api.yaml post /webhooks
Creates a new webhook to send notifications to a URL when a specific event occurs.



# Delete a specific webhook
Source: https://docs.goshippo.com/api-reference/webhooks/delete-a-specific-webhook

/spec/shippoapi/public-api.yaml delete /webhooks/{webhookId}
Deletes a specific webhook using the webhook object ID.



# List all webhooks
Source: https://docs.goshippo.com/api-reference/webhooks/list-all-webhooks

/spec/shippoapi/public-api.yaml get /webhooks
Returns a list of all webhooks you have created.



# Retrieve a specific webhook
Source: https://docs.goshippo.com/api-reference/webhooks/retrieve-a-specific-webhook

/spec/shippoapi/public-api.yaml get /webhooks/{webhookId}
Returns the details of a specific webhook using the webhook object ID.



# Update an existing webhook
Source: https://docs.goshippo.com/api-reference/webhooks/update-an-existing-webhook

/spec/shippoapi/public-api.yaml put /webhooks/{webhookId}
Updates an existing webhook using the webhook object ID.



# Refunding labels
Source: https://docs.goshippo.com/billing-and-invoices/refunding-labels

Learn how to request refunds for unused shipping labels via the Shippo API, including refund statuses and carrier policies.

You can request a refund for any successfully created but unused shipping labels. Refunds include the shipment's postage, additional insurance (if applicable), and any per-label creation fee. Refunds are subject to the policies of the applicable carrier.

## Create a refund

To refund a shipping label, POST the Transaction object ID of the label to the [Refund Endpoint](/api-reference/refunds/list-all-refunds).

<CodeGroup>
  ```shell cURL theme={null}
  curl  https://api.goshippo.com/refunds/\
      -H "Authorization: ShippoToken <API_Token>"\
      -d transaction="4503427478ea45a899e9b54abc4c5803"
  ```

  ```python Python theme={null}
  refund = shippo_sdk.refunds.create(transaction="35ed59f23a514ecfa2faeaed93a00086", async_=False)
  ```

  ```php PHP theme={null}
  $refund = Shippo_Refund::create( array("transaction" => "35ed59f23a514ecfa2faeaed93a00086", "async" => false));
  ```

  ```typescript TypeScript theme={null}
  const refund = await shippo.refunds.create("35ed59f23a514ecfa2faeaed93a00086", false);
  ```

  ```java Java theme={null}
  HashMap<String, Object> createRefundMap = new HashMap<String, Object>();
  createRefundMap.put("transaction", "35ed59f23a514ecfa2faeaed93a00086");
  createRefundMap.put("async", false);

  Refund.create(createRefundMap);
  ```

  ```csharp C# theme={null}
  Refund refund = await sdk.Refunds.CreateAsync(
      new RefundRequestBody()
      {
          Async = false,
          Transaction = "35ed59f23a514ecfa2faeaed93a00086",
      }
  );
  ```
</CodeGroup>

At the moment, you may only request a refund for one shipping label at a time.

The API will return the following response:

```shell theme={null}
{
    "object_created": "2014-04-21T07:12:41.044Z",
    "object_id": "bd7b8379a2e847bcb0818125943dde5d",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-04-21T07:12:41.045Z",
    "status": "QUEUED",
    "transaction": "35ed59f23a514ecfa2faeaed93a00086"
}
```

Possible statuses include:

* `QUEUED`: The request is being processed by Shippo.
* `PENDING`: Waiting for more tracking data from carriers, this could take up to 14 days.
* `ERROR`: Refund rejected, the shipment was found to be used.
* `SUCCESS`: Refund accepted, a negative line item will be added to your next Shippo invoice.

## Information about refunds

* Refunds include the cost of the shipping label, insurance (if applicable), and the Shippo label fee.
* Please note that all refund requests must be submitted within 90 days from the day you purchased the label.
* Once a refund has been claimed, you cannot use the shipping label for sending packages -- it will be rejected.
* Refund requests are processed within 14 business days from the date the refund was requested, provided the label has not been used.
* Refund requests will be rejected if the label is used or scanned by the carrier. Contact [Shippo customer support](https://support.goshippo.com/hc/en-us/requests/new) for more information.
* You will see refunds appear as a negative line item in your next Shippo invoice.
* Although some carriers don't charge you until a package is scanned into their system, you would still need to refund an unused shipping label in Shippo to refund the Shippo label fee and any insurance that you had purchased through Shippo.
* As a reminder, USPS labels must be used within 30 days of purchase. If you have a USPS label you purchased and do not intend to use, you can request a label refund.


# Carrier accounts
Source: https://docs.goshippo.com/carriers/carrier-accounts

Connect Shippo carrier accounts or your own carrier accounts to get shipping rates and purchase labels through the API.

The Shippo API uses carrier accounts to connect to carriers to use their services, such as purchasing a label. You can use the Shippo API to add, modify, and deactivate which carriers your Shippo account uses.
Using the Shippo API, you can connect multiple carrier accounts giving you rates from multiple carriers when you create a shipment.

Shippo supports two types of carrier accounts.

1. Shippo carrier account. These are Shippo’s accounts with specific carriers. Using Shippo carrier accounts you can purchase labels immediately, without creating your account with a carrier. The cost to purchase labels is billed through your Shippo account. Using Shippo carrier accounts you can benefit from discounts negotiated by Shippo.

2. Your own carrier accounts. These are accounts that you have created yourself with a supported carrier. You can add your carrier account details to your Shippo account, allowing Shippo to manage your label creation. The cost of purchasing labels is billed through the account you created with your carrier.

## Connecting Shippo carrier accounts

By default, you have access to Shippo's carrier accounts for U.S. outbound shipments to retrieve shipping rates and purchase labels. When Shippo adds new carrier accounts, they are automatically enabled on your account.

<Info>
  **note**

  UPS requires Terms and Conditions to be accepted, so you must use the Shippo Web App and navigate to the Carriers Settings page and click "Activate Account" for UPS to view and accept the Terms and Conditions.

  Before starting the UPS OAuth authentication flow, it is critical to add every UPS account number to your ups.com user ID. See [this guide](/carriers/adding-ups-accounts/adding-an-account) for instructions.
</Info>

## Connecting your own carrier account

You can connect your own carrier accounts using the [Shippo Web App](https://support.goshippo.com/hc/en-us/articles/360024209911-How-to-Connect-Your-Own-Carrier-Account) or through the API.

Follow this guide to learn about connecting your carriers using the Shippo API. Shippo supports all carriers [listed below](#account-structure-by-carrier) for your own carrier accounts.

To connect your carrier account to your Shippo account, you must create a carrier account object. Each carrier account has different properties that must be shared with Shippo. Refer to the [list below](#account-structure-by-carrier) to identify which properties are required for your chosen carrier.

<Info>
  **Note**

  Before continuing, you must have created your account with your chosen carrier and obtained the required properties as [listed below](#account-structure-by-carrier).
</Info>

The Carrier Account object can be created ([POST](/api-reference/carrier-accounts/create-a-new-carrier-account)), modified or de-activated ([PUT](/api-reference/carrier-accounts/update-a-carrier-account)), or
retrieved ([GET](/api-reference/carrier-accounts/retrieve-a-carrier-account)). You can also list ([GET](/api-reference/carrier-accounts/list-all-carrier-accounts)) all accounts.

To connect your own carrier account and create a carrier account object, follow this example.

<CodeGroup>
  ```shell cURL theme={null}
  curl -X POST https://api.goshippo.com/carrier_accounts/\
      -H "Authorization: ShippoToken <API_TOKEN>" \
      -H 'Content-Type: application/json' \
      -d '{
        "carrier": "fedex",
        "account_id": "<YOUR-FEDEX-ACCOUNT-NUMBER>",
        "parameters": {
          "first_name": "<YOUR_FIRST_NAME>",
          "last_name": "<YOUR_LAST_NAME>",
          "phone_number": "<YOUR_PHONE_NUMBER>",
          "from_address_st": "<YOUR_STREET_ADDRESS>",
          "from_address_city": "<YOUR_CITY>",
          "from_address_state": "<YOUR_STATE>",
          "from_address_zip": "<YOUR_ZIP>",
          "from_address_country_iso2": "<YOUR_COUNTRY>",
          "use_multi_factor_registration": true,
          "verification_option": "<SMS|EMAIL|INVOICE>"
        }
      }'
  ```

  ```python Python theme={null}
  fedex_account = shippo_sdk.carrier_accounts.create(
      components.ConnectExistingOwnAccountRequest(
          carrier="fedex",
          account_id="<YOUR-FEDEX-ACCOUNT-NUMBER>",
          parameters={
              "first_name": "<YOUR_FIRST_NAME>",
              "last_name": "<YOUR_LAST_NAME>",
              "phone_number": "<YOUR_PHONE_NUMBER>",
              "from_address_st": "<YOUR_STREET_ADDRESS>",
              "from_address_city": "<YOUR_CITY>",
              "from_address_state": "<YOUR_STATE>",
              "from_address_zip": "<YOUR_ZIP>",
              "from_address_country_iso2": "<YOUR_COUNTRY>",
              "use_multi_factor_registration": True,
              "verification_option": "<SMS|EMAIL|INVOICE>"
          },
          active=True
      )
  )
  ```

  ```php PHP theme={null}
  $fedex_account = Shippo_CarrierAccount::create(array(
      'carrier' => 'fedex',
      'account_id' => '<YOUR-FEDEX-ACCOUNT-NUMBER>',
      'parameters' => array('first_name' => '<YOUR_FIRST_NAME>', 'last_name' => 'YOUR_LAST_NAME', 'phone_number' => '<YOUR_PHONE_NUMBER>', 'from_address_st' => '<YOUR_STREET_ADDRESS>', 'from_address_city' => '<YOUR_CITY>', 'from_address_state' => '<YOUR_STATE>', 'from_address_zip' => '<YOUR_ZIP>', 'from_address_country_iso2' => '<YOUR_COUNTRY>', 'use_multi_factor_registration' => true, 'verification_option' => '<SMS|EMAIL|INVOICE>'),
      'test' => false,
      'active' => true
  ));
  ```

  ```typescript TypeScript theme={null}
  const fedExParameters: FedExConnectExistingOwnAccountParameters = {
      firstName: "<YOUR_FIRST_NAME>",
      lastName: "<YOUR_LAST_NAME>",
      phoneNumber: "<YOUR_PHONE_NUMBER>",
      fromAddressSt: "<YOUR_STREET_ADDRESS>",
      fromAddressCity: "<YOUR_CITY>",
      fromAddressState: "<YOUR_STATE>",
      fromAddressZip: "<YOUR_ZIP>",
      fromAddressCountryIso2: "<YOUR_COUNTRY>",
      useMultiFactorRegistration: true,
      verificationOption: "<SMS|EMAIL|INVOICE>"
  }
  const fedExAccount = await shippo.carrierAccounts.create({
      carrier: CarriersEnum.Fedex.valueOf(),
      accountId: "<YOUR-FEDEX-ACCOUNT-NUMBER>",
      parameters: fedExParameters,
      test: true,
      active: true
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> accountMap = new HashMap<String, Object>();
  accountMap.put("carrier", "fedex");
  accountMap.put("account_id", "<YOUR-FEDEX-ACCOUNT-NUMBER>");
  accountMap.put("parameters", new HashMap<String, Object>() {
      {
          put("first_name", "<YOUR_FIRST_NAME>");
          put("last_name", "YOUR_LAST_NAME");
          put("phone_number", "<YOUR_PHONE_NUMBER>");
          put("from_address_st", "<YOUR_STREET_ADDRESS>");
          put("from_address_city", "<YOUR_CITY>");
          put("from_address_state", "<YOUR_STATE>");
          put("from_address_zip", "<YOUR_ZIP>");
          put("from_address_country_iso2", "<YOUR_COUNTRY>");
          put("use_multi_factor_registration", true);
          put("verification_option", "<SMS|EMAIL|INVOICE>");
      }
  });
  accountMap.put("test", Boolean.FALSE);
  accountMap.put("active", Boolean.TRUE);

  CarrierAccount fedex_account = CarrierAccount.create(accountMap);
  ```

  ```cs C# theme={null}
  CarrierAccount fedexAccount = await sdk.CarrierAccounts.CreateAsync(
      new ConnectExistingOwnAccountRequest()
      {
          Carrier = CarriersEnum.Fedex.Value(),
          AccountId = "<YOUR-FEDEX-ACCOUNT-NUMBER>",
          Parameters = ConnectExistingOwnAccountRequestParameters.CreateFedExConnectExistingOwnAccountParameters(
              new FedExConnectExistingOwnAccountParameters()
              {
                  FirstName = "<YOUR_FIRST_NAME>",
                  LastName = "<YOUR_LAST_NAME>",
                  PhoneNumber = "<YOUR_PHONE_NUMBER>",
                  FromAddressSt = "<YOUR_STREET_ADDRESS>",
                  FromAddressCity = "<YOUR_CITY>",
                  FromAddressState = "<YOUR_STATE>",
                  FromAddressZip = "<YOUR_ZIP>",
                  FromAddressCountryIso2 = "<YOUR_COUNTRY>",
                  UseMultiFactorRegistration = true,
                  VerificationOption = "<SMS|EMAIL|INVOICE>",
              }
          ),
          Active = true,
          Test = false,
      }
  );
  ```
</CodeGroup>

For FedEx, the shipping address in `from_address_*` must match what you have on file with FedEx (see your [fedex.com profile](https://fedex.com)). The `verification_option` and verification fields (`verification_pin`, `verification_invoice_number`, `verification_invoice_amount`, `verification_invoice_date`, `verification_invoice_currency`) are optional and depend on the verification method you use (SMS, EMAIL, CALL, or INVOICE).

The API will respond with the JSON serialized carrier account object:

```json theme={null}
{
    "account_id": "<YOUR-FEDEX-ACCOUNT-NUMBER>",
    "active": true,
    "carrier": "fedex",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "shippotle@shippo.com",
    "parameters": {
        "first_name": "<YOUR_FIRST_NAME>",
        "last_name": "YOUR_LAST_NAME",
        "phone_number": "<YOUR_PHONE_NUMBER>",
        "from_address_st": "<YOUR_STREET_ADDRESS>",
        "from_address_city": "<YOUR_CITY>",
        "from_address_state": "<YOUR_STATE>",
        "from_address_zip": "<YOUR_ZIP>",
        "from_address_country_iso2": "<YOUR_COUNTRY>",
        "use_multi_factor_registration": true,
        "verification_option": "<SMS|EMAIL|INVOICE>"
    },
    "test": false,
    "active": true,
    "is_shippo_account": false,
    "metadata": ""
}
```

Refer to our [carrier capabilities](/carriers/carrier-capabilities) for a full list of supported carriers and their capabilities.

## Using carrier accounts in Shipments

You can specify which carrier accounts you want to use on a per-shipment basis by passing in each account's `object_id` in the shipment's `carrier_accounts` field as a list. If you don't specify which accounts to use, Shippo will use all your active accounts for this shipment.

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -d address_from="d799c2679e644279b59fe661ac8fa488"\
      -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
      -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
      -d carrier_accounts=["b741b99f95e841639b54272834bc478c", "b741b99f95e841639b54272834bc478c" ]\
      -d async=false
  ```

  ```python Python theme={null}
  shipment = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          parcels=[parcel],
          carrier_accounts=['b741b99f95e841639b54272834bc478c'],
          async_=False
      )
  )
  ```

  ```php PHP theme={null}
  $shipment = Shippo_Shipment::create(array(
      'address_from'=> $fromAddress,
      'address_to'=> $toAddress,
      'parcels'=> array($parcel),
      'carrier_accounts' => array('b741b99f95e841639b54272834bc478c'),
      'async' => false
  ));
  ```

  ```typescript TypeScript theme={null}
  const shipment = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
      carrierAccounts: ['b741b99f95e841639b54272834bc478c'],
      async: false
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", toAddressMap);
  shipmentMap.put("address_from", fromAddressMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("carrier_accounts", new String[]{"b741b99f95e841639b54272834bc478c"});
  shipmentMap.put("async", false);

  Shipment shipment = Shipment.create(shipmentMap);
  ```

  ```cs C# theme={null}
  Shipment shipment = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
          CarrierAccounts = new List<string>() { "b741b99f95e841639b54272834bc478c" },
          Async = false,
      }
  );
  ```
</CodeGroup>

## Filtering carrier accounts

You can filter carrier accounts by `carrier` and `account_id`:

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/carrier_accounts/?carrier=fedex\
      -H "Authorization: ShippoToken <API_TOKEN>"\
  ```

  ```python Python theme={null}
  shippo_sdk.carrier_accounts.list(
      operations.ListCarrierAccountsRequest(
          carrier=components.CarriersEnum.FEDEX
      )
  )
  ```

  ```php PHP theme={null}
  Shippo_CarrierAccount::all(array('carrier'=> 'fedex'))
  ```

  ```typescript TypeScript theme={null}
  shippo.carrierAccounts.list({ carrier: CarriersEnum.Fedex });
  ```

  ```java Java theme={null}
  CarrierAccount.getByCarrier("fedex");
  ```

  ```cs C# theme={null}
  await sdk.CarrierAccounts.ListAsync(
      new ListCarrierAccountsRequest()
      {
          Carrier = CarriersEnum.Fedex,
      }
  );
  ```
</CodeGroup>

## Account structure by carrier

Each carrier has its own type of fields. Browse the list below to find the required fields for the carriers you want to use.

### APC Postal

***

```json theme={null}
{
    "carrier": "apc_postal",
    "account_id": "12345", // APC Postal Account ID
    "parameters": {
              "processing_site": "NJ" // APC Postal Processing Site
               },
    ...
}
```

### APG

***

```json theme={null}
{
   "carrier": "apg",
   "account_id": "12345", // Unique identificator of account
   "parameters": {
       "account_id": "shippo", // APG Account username
       "password": "shippo", // APG Account password
       "sender_code": "sti.us.sender_code" // APG Sender Code
    }
}
```

### Asendia

***

```json theme={null}
{
    "carrier": "asendia_us",
    "account_id": "123", // Asendia account number
    "parameters": {
        "asendia_user_login": "usertesting",  // Asendia user login
        "asendia_user_password": "1234512345",  // Asendia user password
        "ftp_username": "testtest",
        "ftp_password": "xyz123",
        "company_name": "Your Company Name", // Required (displays on manifest)
        "permit_no": "234"
    },
    ...
}
```

### Australia Post

***

#### Australia Post eParcel

```json theme={null}
{
    "carrier": "australia_post",
    "account_id": "123456", // Australia Post account number
    "parameters": {
        "api_key": "yourapikey", // Australia Post API key
        "password": "testpass" // Australia Post password
    },
    ...
}
```

#### Australia Post MyPost

```json theme={null}
{
  "account_id": "12345",
  "carrier": "australia_post",
  "parameters": {
    "is_mypost": true,
    "merchant_token": "yourPartnerToken"
  },
  "test": false,
  "active": true
}
```

### BetterTrucks

***

```json theme={null}
{
    "carrier": "better_trucks",
    "account_id": "100", // unique identifier of account
    "parameters": {
        "api_key": "XXXX-XXXXX-XXXXX",  // API Key provided by BetterTrucks
        "account_id": "100"  // Identifier for account
    },
    "test": false,
    "active": true
}
```

### Canada Post

***

```json theme={null}
{
    "carrier": "canada_post",
    "account_id": "shippo_api", // Canada Post API username
    "parameters": {
        "api_password": "HipposDontLie!", // Canada Post API password
        "customer_number": "413781", // Canada Post customer number
        "contract_id": "910412", // Canada Post contract number (optional)
        "payment_method": "Account" // Payment method for account, 'CreditCard' or 'Account' (optional)
        "use_manifests": true // Indicates that shipments will be linked with a manifest (contract customers only; optional)
    },
    ...
}
```

### Deutsche Post

***

```json theme={null}
{
    "carrier": "deutsche_post",
    "account_id": "test@test.com", // Deutsche Post username
    "parameters": {
        "password": "testpass" // Deutsche Post password
    },
    ...
}
```

### DHL eCommerce

***

```json theme={null}
{
    "carrier": "dhl_ecommerce",
    "account_id": "dhl_ecommerce", // Custom account identifier
    "parameters": {
        "username": "HipposDontLie!", // DHL eCommerce client ID
        "password": "shipshippo", // DHL eCommerce client secret
        "pickup_no": "123123", // DHL eCommerce pickup number
        "facility_code": "23" // DHL eCommerce facility code
    },
    ...
}
```

### DHL Express

***

```json theme={null}
{
    "carrier": "dhl_express",
    "account_id": "123456789", // DHL account number
    "parameters": {
        "password": "", // Password from DHL Express
        "site_id": "", // Site ID from DHL Express (from DHL account manager/rep or email)
        "payment_country": "US" // ISO2 code of the country associated with the account
    },
    "active": true,
    "is_shippo_account": false
}
```

### DHL Germany

***

```json theme={null}
{
    "carrier": "dhl_germany",
    "account_id": "2222222222", // The first 10 digits of your DHL account number
    "parameters": {
        "business_customer_portal_username": "dhl_shippo", // DHL username for www.dhl-geschaeftskundenportal.de
        "business_customer_portal_password": "HipposDontLie!", // DHL password for www.dhl-geschaeftskundenportal.de
        "default_participation_code": "01", // The last 2 digits of your DHL account number
        "tracking_account": "978346", // DHL tracking account (optional)
        "tracking_password": "HipposAreBack!" // DHL tracking password (optional)
    },
    ...
}
```

### DPD UK

***

```json theme={null}
{
  "carrier": "dpd_uk",
  "account_id": "abc123", // DPD UK Account Name
  "parameters": {
    "username": "USERNAME", // DPD UK Username
    "password": "PASSWORD" // DPD UK Password
  },
  ...
}
```

### ePost Global

***

```json theme={null}
{
  "carrier": "rr_donnelley",
  "account_id": "1111",
  "parameters": {
    "processing_site": "LAX"
    "company_name": "Company"
  },
  ...
}
```

### EVRi UK

***

<Info>
  **Note**

  Hermes UK have changed their name to EVRi. To support existing customers already using this carrier, we have continued to use the `hermes` name in our API configuration.
</Info>

```json theme={null}
{
    "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"
               },
    ...
}
```

### FedEx

***

```json theme={null}
{
  "carrier": "fedex",
  "account_id": "321123", //Fedex account number
  "parameters": {
    "first_name": "Hippo",  //Your first name
    "last_name": "Hippovich", // Your last name
    "phone_number": "1234567890", // Your phone number
    "from_address_st": "250 Union St", // Shipping address must match what you have on file with FedEx (see fedex.com profile)
    "from_address_city": "San Francisco",
    "from_address_state": "CA",
    "from_address_zip": "94133",
    "from_address_country_iso2": "US",
    "use_multi_factor_registration": true, //Determines use of the multi-factor registration workflow. If true, the account will be registered using the multi-factor registration workflow. If false, the account will be registered using the standard registration workflow.
    "verification_option": "SMS", //Determines the verification option to use for the account registration (Enum: SMS, EMAIL, CALL, INVOICE).
    "verification_pin": "12345", //(optional) The PIN to verify the account.
    "verification_invoice_number": "9922232", //(optional) The invoice number to verify the account.
    "verification_invoice_amount": "340", //(optional) The invoice amount to verify the account.
    "verification_invoice_date": "2024-03-09", //(optional) The invoice date to verify the account. In the format `YYYY-MM-DD`.
    "verification_invoice_currency": "12345" //(optional) The invoice currency to verify the account.
  },
  "active": true,
  "test": false
}
```

### Globegistics

***

```json theme={null}
{
    "carrier": "globegistics",
    "account_id": "Name of this account", // The name of this account on Shippo
    "parameters": {
              "account_number": "123456", // Globegistics Account Number
              "api_key": "123456789", // Globegistics API Key
               },
    ...
}
```

### GLS US

***

```json theme={null}
{
    "carrier": "gls_us",
    "account_id": "1111", // GLS US account number
    "parameters": {
    	"api_token": "your_account_pw", // GLS US account password
	"username": "your_account_username", // GLS US account username
    },
...
}
```

### LaserShip

***

```json theme={null}
{
    "carrier": "lasership",
    "account_id": "01isf7yzmpsbfy02172gyu2ek78", // LaserShip API key
    "parameters": {
        "lasership_apiid": "c27908r07cc20r893270adsc0402", // LaserShip API ID
        "critical_pull_time": "16:00"
    },
    ...
}
```

### Mondial Relay

***

```json theme={null}
{
    "carrier": "mondialrelay",
    "account_id": "9328271", // Mondial Relay merchant ID
    "parameters": {
        "key": "JBHOS29JH19N7V6SJ89MK10K" // Mondial Relay key
    },
    ...
}
```

### OnTrac

***

```json theme={null}
{
    "carrier": "ontrac",
    "account_id": "37", // OnTrac account number
    "parameters": {
        "password": "testpass" // OnTrac provided password
    },
    ...
}
```

### Purolator

***

```json theme={null}
    "carrier": "purolator",
    "account_id": "shippo_purolator", // Purolator account number
    "parameters": {
        "production_key": "345345", // Purolator production key
        "production_key_password": "abcdef" // Purolator production key password
    },
    ...
}
```

### Swyft

***

```json theme={null}
{
    "carrier": "swyft",
    "object_owner": "user@shippo.com",
    "account_id": "unique_account_id",
    "parameters": {
        "api_key": "11111-22222-33333-44444" // Swyft API Key
    },
    "test": false,
    "active": true,
    "is_shippo_account": false,
    "metadata": "Account Name",
    "carrier_name": "Swyft"
}
```

### UDS

***

```json theme={null}
{
    "carrier": "uds",
    "account_id": "12345", // UDS Client ID
    "parameters": {
      "client_key": "grteehj54tjgf", // UDS Client Key
      "UDS_TRACK_API_USER_ID": "shippo", // UDS Username for tracking
      "UDS_TRACK_API_PASSWORD": "shippo", // UDS Password for tracking
    }
}
```

### UPS

***

```json theme={null}
{
    "carrier": "ups",
    "active": true,
    "metadata": "UPS Account",
    "account_id": "myupsuser", // UPS user ID
    "parameters": {
        "account_number": "AB1234", // UPS account number
        "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": "Shippo",
        "currency_code": "USD",
        "email": "hippo@shippo.com",
        "full_name": "Shippo Meister",
        "has_invoice": false,
        "invoice_controlid": 1234,
        "invoice_date": 20210529,
        "invoice_number": 1112234,
        "invoice_value": 11.23,
        "phone": 1112223333,
        "title": "Manager",
        "ups_agreements": true,
        "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,
        "surepost": false, // Add Surepost rating (optional)
        "cost_center": "shippo", // Mail Innovations cost center (optional)
        "usps_endorsement": "3", // Mail Innovations USPS endorsement (optional)
        "customer_id": "1234", // Mail Innovations UPS customer ID (optional)
        "customer_guid": "1234-abcde" // Mail Innovations UPS customer GUID (optional)
    },
    "test": false
}

```

### Veho

***

```json theme={null}
{
    "carrier": “veho”,
    "account_id": "Name of this account", // The name of this account on Shippo
    "parameters": {
              "api_key": "123456789", // Veho API Key
               },
    "test": false,
    "active": true,
}
```


# Carrier capabilities
Source: https://docs.goshippo.com/carriers/carrier-capabilities

View supported features, service areas, and account requirements for each carrier available through the Shippo API.

Shippo provides access to a global network of shipping providers. Each carriers has its own rules and restrictions, you can find details here.

<img alt="APC postal logo" />

## APC Postal

Countries served:\
US to international destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Manifests
* Instalabel single call label generation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, ZPL II

Account information required:

* APC Postal Account Number
* APC Postal Processing Site

***

<img alt="APG logo" />

## APG

Countries Served:\
US outbound international shipments to Australia, New Zealand, United Kingdom, Singapore, and Israel.

Supported features:

* Shipping labels
* Tracking
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 2.3×7.5 inch PNG, 8.5×11 inch PDF, 4×6 inch PDF, 2.3×7.5 inch PDF, ZPL II, A4 PDF, A6 PDF

Account information required:

* APG Username
* APG Password
* APG Sender Code

***

<img alt="Asendia logo" />

## Asendia

Service area:\
United States outbound shipments to international destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Manifests
* Signature confirmation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, ZPL II

Account information required:

* Asendia User Login
* Asendia User Password
* Asendia FTP Username
* Asendia FTP Password
* Company Name Registered with Asendia
* Asendia Permit Number
* Asendia Rate Table (optional, to display rates before purchasing. Please contact [support@shippo.com](mailto:support@shippo.com) for more details)

***

<img alt="Australia Post logo" />

## Australia Post

Countries served:\
Australia outbound shipments to domestic and international destinations

Supported features:

* Shipping rates
* Shipping labels
* Australia address validation
* Tracking
* Manifests
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A5 PDF, A6 PDF, ZPL II
* Signature confirmation

<Info>
  **note**

  Australia Post supports ZPL II for [CN22 labels](https://auspost.com.au/business/shipping/international-shipping/cn22-changes) but do support ZPL II  for CN23 labels.
</Info>

Account information required:

* Australia Post account number
* Australia Post API key\
  [(see our FAQ on how to get get your Australia Post API key)](http://support.goshippo.com/hc/en-us/articles/210122883-How-do-I-connect-my-Australia-Post-account-with-Shippo-)
* Australia Post password

***

<img alt="Aramex logo" />

## Aramex Australia

Shippo offers a Shippo carrier account upon sign up.

Countries served:\
Australia outbound shipments to domestic destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A6 PDF, ZPL II

***

<img alt="Better Trucks logo" />

## Better Trucks

Countries served:\
United States outbound shipments to domestic destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, PDF A4 & PDF A6 labels

***

<img alt="Canada Post logo" />

## Canada Post

Countries served:\
Canadian outbound shipments to domestic and international destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Manifest
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF, 4×6 inch PDF

Account information required:

* Canada Post customer number
* Canada Post API username and password\
  [(see our FAQ on how to ger your Canada Post API usernames and password)](http://support.goshippo.com/hc/en-us/articles/201772755-Where-do-I-get-my-Canada-Post-API-username-and-password-)
* Canada Post contract ID (if you are a contract customer)
* Canada Post payment method\
  (If you are a contract customer, select credit card or account)

**Test Mode:** Canada Post requires a different API username and password for test mode. [Read our FAQ to see how to get your test credentials.](http://support.goshippo.com/hc/en-us/articles/201772755-Where-do-I-get-my-Canada-Post-API-username-and-password-)

***

<img alt="Chronopost logo" />

## Chronopost

Countries served:\
France outbound shipments to domestic destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* Signature Confirmation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, A4 PDF, A6 PDF

***

<img alt="Colissimo logo" />

## Colissimo

Countries served:\
France outbound shipments to domestic destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, PDF A4 & PDF A6 labels

***

<img alt="Correos logo" />

## Correos

Countries served:\
Spain outbound shipments to domestic destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A6 PDF

***

<img alt="Deutsche Post logo" />

## Deutsche Post

Shippo offers a default Shippo carrier account upon sign up.

Countries served:\
Germany outbound shipments to domestic and international destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF
* Instalabel single call label generation

***

<img alt="DHL eCommerce logo" />

## DHL eCommerce

Countries served:\
United States outbound shipments to domestic and international destinations only

Supported features:

* Shipping labels
* Tracking
* Dangerous goods support
* Manifests
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF, 4×6 inch PDF, A4 PDF, A6 PDF, ZPL II
* Instalabel single call label generation
* Signature Confirmation

Account information required:

* DHL eCommerce Client ID
* DHL eCommerce Password
* DHL eCommerce Pickup Number
* DHL eCommerce Facility Code

***

<img alt="DHL Express logo" />

## DHL Express

For international shipments originating from United States, Shippo offers a discounted Shippo carrier account upon sign up.

Countries served:\
Global

Supported features:

* Discounted shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF, 4×6 inch PDF, ZPL II

Account information required:\
For all other outbound countries, and U.S. businesses who'd like to use their own DHL accounts, please enter:

* DHL Express account number
* Contact us at `support@shippo.com` if you have your own DHL Express account to access your rates.
* To use your own DHL Express account with Shippo, your account will need to be whitelisted by your DHL Express account manager. Please contact your DHL Express account manager and let them know you would like to connect to Shippo to access your rates.

***

<img alt="DHL Germany logo" />

## DHL Germany

Countries served:\
German and Austria outbound shipments to domestic and international destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* [Reference fields](/carriers/carrier-reference-fields)s
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 4×6 inch PDF, 4×8 inch PDF, 8.5×11 inch PDF, PNG, A4 PDF, A6 PDF

Account information required:

To use your own account, you'll need:

* DHL Germany account number (The first 10 digits of your DHL account number)
* DHL Germany business customer portal username (DHL username for [www.dhl-geschaeftskundenportal.de](http://www.dhl-geschaeftskundenportal.de))
* DHL Germany business customer portal password (DHL password for [www.dhl-geschaeftskundenportal.de](http://www.dhl-geschaeftskundenportal.de))
* DHL Germany default participation code (The last 2 digits of your DHL account number)
* DHL Germany tracking username (optional, only used for tracking)
* DHL Germany tracking password (optional, only used for tracking)

**Test Mode:** DHL Germany requires a different credentials for test mode. It can be found on add carrier account page.

***

<img alt="DPD UK logo" />

## DPD UK

Countries served:\
UK outbound shipments to domestic destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Scan based billing
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 4×8 inch PDF, A4 PDF, A6 PDF

Restrictions:

* Only the Two Day service can be used to ship to Ireland and islands (i.e. IM, JE, GG, IE).
* Packages under 30kg.
* For the package to be applicable for drop-off at a parcel shop, it should be under 20kg in weight. For dimension, the L*H*W should be less than 60cm*60cm*60cm OR no two sides to exceed 1.2m collectively. If these weight and dimension restrictions are not met, the parcel will only be available for courier collection.

***

<img alt="DPD DE logo" />

## DPD DE

Countries served:\
Germany outbound shipments to domestic destinations only

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Scan based billing
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 4×8 inch PDF, A4 PDF, A6 PDF

Restrictions:

* Packages under 20kg are allowed for DPD Classic.
* Packages should have a length of up to 100 cm and length plus girth should be up to 250cm.

***

<img alt="ePost Global logo" />

## ePost Global

Countries served:\
US-originated domestic and international shipments

Supported features:

* Shipping labels
* Tracking
* Manifests
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, ZPL II
* Instalabel single call label generation

***

<img alt="Evri logo" />

## Evri

Countries served:\
UK outbound shipments to AT, BE, CZ, DK, FI, FR, DE, HU, IE, IT, LU, MC, NL, PT, SK, ES, SE, and UK

Supported Features:

* Shipping rates
* Shipping labels
* Tracking
* Signature service
* Scan based billing
* [QR code](/shipments/qr-code) for in-store label printing
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 8.5×11 inch PDF, 4×6 inch PDF, ZPL II, A4 PDF, A6 PDF
* Evri ParcelShop Service, use locations to find a nearby ParcelShop
* Evri Courier Collection Service, have parcel picked up

Restrictions:

* Certain remote zip codes will incur a remote delivery surcharge (i.e. IM,HS,ZE).
* Packages under 15kg.

***

<img alt="FedEx logo" />

## FedEx

[**Don't have a FedEx account? Open a discounted FedEx account now with Shippo!**](https://advantagemember.van.fedex.com/7502/)

Countries served:\
Global

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Signature confirmation
* 3rd party billing
* Multi-piece shipments
* Instalabel single call label generation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 8.5×11 inch PDF, 4×6 inch PDF, ZPL II, A4 PDF, A6 PDF

<Info>
  **note**

  When using your own FexEx account with [Instalabel single call label generation](/guides/single-call), the response rate amount will be \$0. The label generated is still valid and FedEx will still charge your account.
</Info>

<Info>
  **FedEx One Rate**

  For eligible service levels, FedEx returns a One Rate variant alongside the standard rate. Identify it by `servicelevel.terms: "ONERATE"` — it shares the same `servicelevel.token` as the standard-rate object but is a separate rate with its own `amount`. For example, a `fedex_2_day` response may include one rate with `terms: ""` at $26.34 and another with `terms: "ONERATE"` at $11.75. To purchase the One Rate option, create a transaction against the `ONERATE` rate object like any other rate — Shippo passes the required flag to FedEx automatically, no extra field needed.
</Info>

Account information required:

* FedEx account number
* FedEx Smartpost hub ID (required for FedEx Smartpost)

**Test Mode:** FedEx requires a different account and for test mode. Please connect a FedEx test account on Shippo with your test mode credentials from the [FedEx Web Services portal](http://www.fedex.com/us/developer/web-services/index.html).

***

<img alt="Globegistics logo" />

## Globegistics

Countries served:\
US to international destinations

Supported features:

* Shipping rates
* Shipping labels
* Manifests
* Tracking
* Instalabel single call label generation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF

Account information required:

* Globegistics Account Number
* Globegistics API Key

***

<img alt="GLS United States logo" />

## GLS United States

Service area:\
Western United States

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Signature Confirmation
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 8.5×11 inch PDF, 4×6 inch PDF, ZPL II
* Instalabel single call label generation

Account information required:

* GLS US account number
* GLS US account username
* GLS US account password

***

<img alt="Jitsu logo" />

## Jitsu

Countries served:\
United States outbound shipments to domestic destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Instalabel single call label generation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, ZPL II

***

<img alt="Lasership logo" />

## Lasership

Service area:\
Eastern United States

Supported features:

* Support for [Routed Delivery](https://lasership.com/services/custom-delivery-solutions/)

and more services

* Shipping labels
* Tracking
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A6 PDF, ZPL II

Account information required:

* LaserShip API Key
* LaserShip API ID
* Critical pull time

***

<img alt="Mondial Relay logo" />

## Mondial Relay

Countries served:\
France outbound shipments to domestic destinations only

Supported features:

* Shipping labels
* Tracking
* Location finder
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF

Shippo offers highly discounted rates -- you don't need to have your own account!\
If you prefer to use your own account, you'll need:

* Mondial Relay merchant ID
* Mondial Relay key

Mondial Relay requires a different merchant ID and key for test mode.

***

<img alt="OnTrac logo" />

## OnTrac

Service area:\
Western United States

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A6 PDF, ZPL II
* Signature confirmation
* 3rd party billing
* Collection on delivery (COD)
* Saturday delivery
* Carrier insurance
* [Reference fields](/carriers/carrier-reference-fields)
* Instalabel single call label generation

Account information required:

* OnTrac account number
* OnTrac API Password

Please email [softwaresupport@ontrac.com](mailto:softwaresupport@ontrac.com) or call 877-225-6837 to request your OnTrac API password.

***

<img alt="Poste Italiane logo" />

## Poste Italiane

Countries served:\
Italy outbound shipments to domestic destinations only

Supported features:

* Shipping labels
* Tracking
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF, PDF A4, PDF A6

Shippo offers highly discounted rates – you don’t need to have your own account!

***

<img alt="Purolator logo" />

## Purolator

Countries served:\
Canadian outbound shipments to domestic and international destinations

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Manifests
* Signature Confirmation
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 8.5×11 inch PDF, ZPL II
* Instalabel single call label generation

Account information required:\
Please register with the [Purolator Resource Center](https://eship.purolator.com/SITE/en/createnewuser.aspx) first. Select: "I'm integrating Purolator E-Ship Web Services into a website or application that won't be re-sold."

* Purolator production key
* Purolator production key password
* Purolator account number

***

<img alt="Royal Mail logo" />

## Royal Mail OBA (BYOA)

Countries served:\
UK outbound shipments to domestic destinations only.

* Shipping rates
* Shipping labels
* Tracking
* Label Cancellation/Refunds
* Returns
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 2.3 x 7.5 inch PDF, 2.3 x 7.5 inch PNG, 4 x 8 inch PDF, 4×6 inch PDF, 8.5×11 inch PDF, A4 PDF, A5 PDF, A6 PDF, ZPL II, PNG

Please note that Royal Mail refunds are only allowed 12 days after the label was purchased.

***

<img alt="Royal Mail logo" />

## Royal Mail Tracked

To access **Royal Mail Tracked 24 and 48**, you can use Shippo’s account.
This means you can start shipping with Royal Mail right away — no need to create and manage your own carrier account.

With Royal Mail through Shippo you can:

* Ship to any domestic address in Great Britain and Northern Ireland
* Access next-day delivery (Tracked 24) or 2-3 day delivery (Tracked 48), with or without signature
* Print label [formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): 4×6 inch PDF, A4 PDF or generate QR codes for printer-free drop-off
* Drop off packages at Post Offices, lockers, Parcel Post Boxes, or partner shops
* Track all shipments via the Shippo API
* Label Cancellation/Refunds

***

<img alt="Swyft logo" />

## Swyft

Service Area:\
New York City, Chicago, Los Angeles, and Atlanta

Supported features:

* Shipping labels
* Tracking
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 2.3×7.5 inch PNG, 8.5×11 inch PDF, 4×6 inch PDF, 2.3×7.5 inch PDF, ZPL II, A4 PDF, A6 PDF

Account information required:

* Swyft API Key

***

<img alt="UDS logo" />

## UDS

Service Area:\
Illinois, Idaho, Southern Wisconsin

Supported features:

* Shipping labels
* Tracking
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 2.3×7.5 inch PNG, 8.5×11 inch PDF, 4×6 inch PDF, 2.3×7.5 inch PDF, ZPL II, A4 PDF, A6 PDF

Account information required:

* Client ID
* Client Key
* Username
* Password

***

<img alt="UPS logo" />

## UPS

Countries served:\
Global

Supported features:

* Shipping rates
* Shipping labels
* Tracking
* Signature confirmation
* 3rd party billing
* Collection on delivery (COD)
* Multi-piece shipments
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 8.5×11 inch PDF, 4×6 inch PDF, ZPL II
* Instalabel single call label generation

<Info>
  **note**

  When using your own UPS account with [Instalabel single call label generation](/guides/single-call), the response rate amount will be \$0. The label generated is still valid and UPS will still charge your account.
  Instalabel single call label generation is not available for UPS Digital Access Program accounts.
</Info>

**To access your negotiated UPS rates,** please connect your account through the UPS full setup workflow from the [Carriers tab](https://goshippo.com/user/carriers/) on your dashboard. [Learn more here.](http://support.goshippo.com/hc/en-us/articles/204781715-How-do-I-connect-my-UPS-account-with-Shippo-).

Account information required:

* UPS User ID
* UPS account number
* UPS Password
* UPS Mail Innovations cost center identifier (required for UPS Mail Innovations)
* UPS Mail Innovations USPS endorsement (required for UPS Mail Innovations)

***

<img alt="USPS logo" />

## USPS

Shippo offers a discounted Shippo carrier account upon sign up.

Countries served:\
United States outbound shipments to domestic and international destinations

Supported features:

* Discounted shipping rates
* Shipping labels
* Tracking
* Manifests
* Signature confirmation
* Scan-based return labels
* [QR code](/shipments/qr-code) for in-store label printing
* [Reference fields](/carriers/carrier-reference-fields)
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 2.3×7.5 inch PNG, 8.5×11 inch PDF, 4×6 inch PDF, 2.3×7.5 inch PDF, ZPL II, A4 PDF, A6 PDF
* Instalabel single call label generation

Shipments to Military Mail (APO, DPO, FPO, MPO), U.S. Territories, and Freely Associated States requires Customs Forms.

***

<img alt="Veho logo" />

## Veho

Countries served:
United States outbound shipments to domestic destinations

Supported features:

* Shipping rates
* Shipping labels
* Refund
* Multi-piece support
* [Label formats](/shipments/shipping-label-sizes#shipping-label-format-sizes): PNG, 4×6 inch PDF, 4×8 inch PDF, A4 PDF, A6 PDF, ZPL II
* Instalabel single call label generation
* Tracking

Account information required:

* Veho API Key

Restrictions:

* Maximum weight: 50 lbs
* Maximum dimensions: 72 inches for each dimension (height, length, and width)

***


# Carrier authorization using OAuth
Source: https://docs.goshippo.com/carriers/carrier-o-auth

Authorize carrier accounts like UPS using OAuth so Shippo can request rates and buy labels on your behalf.

To protect your account security, some carriers (for example UPS) require you to use [OAuth](https://oauth.net/2/) 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](/partner-integration/business-cases#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](/platform-accounts/platform-accounts).

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.

<Info>
  **INFO**

  Before you begin, this guide assumes you have already created your own account with your carrier.
</Info>

<Info>
  **Note**

  Before starting the UPS OAuth authentication flow, it is critical to add every UPS account number to your ups.com user ID. See [this guide](/carriers/adding-ups-accounts/adding-an-account) for instructions.
</Info>

## 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](#get-your-carrier-object_id)).

To add a new carrier, refer to our [Carrier accounts guide](/carriers/carrier-accounts). Each carrier can require unique [parameters](/carriers/carrier-accounts#account-structure-by-carrier)

The following example shows how to connect a [UPS account](/carriers/carrier-accounts#ups).

**Request:**

```shell Add carrier request theme={null}
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
}'
```

**Response:**

```json Add carrier response theme={null}
{
  "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.

**Request:**

```shell List carriers request theme={null}
curl https://api.goshippo.com/carrier_accounts \
 -H "Authorization: ShippoToken <API_TOKEN>" \
 -H "SHIPPO-ACCOUNT-ID: <ShippoAccountID>"
```

**Response:**

```json List carriers response theme={null}

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

```shell Start carrier validation request theme={null}
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](https://www.oauth.com/oauth2-servers/redirect-uris/) 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`.

<Info>
  **Note**

  Shippo securely stores your users [refresh token](https://oauth.net/2/refresh-tokens/) meaning we don't require your user to authorize again. However, if there are any issues during the refresh process, we will require your user to authorize again.
</Info>

## Check your carrier status

You can check the status of a connected carrier at any time using the carrier object\_id.

```shell Get carrier account request theme={null}
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.

```json object_info sample theme={null}
{
 "object_info": {
   "authentication": {
     "type": "oauth",
     "status": "connected"
   }
 }
}
```


# Carrier reference fields
Source: https://docs.goshippo.com/carriers/carrier-reference-fields

Add custom reference information like order numbers to your shipping labels using supported carrier reference fields.

Some carriers enable you to add reference information to your label. Depending on your application, you could use this to add information like customer order numbers or other reference details to a shipping label.
For example, USPS print reference fields at the bottom of the their label.

<img alt="USPS sample label with the location of ref1 and ref2 highlighted" />

## Supported carriers

Not every carrier supports this and different carriers enable this in different ways.
Refer to this table for details on Shippo supported carriers that have enabled this feature.

| Carrier                | Supports `reference_1` | Supports `reference_2` | Limits (characters per field) | Sample                                            | Notes                                                                                 |
| ---------------------- | ---------------------- | ---------------------- | ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- |
| APG                    | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| Asendia                | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| Australia Post         | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| Canada Post            | ◉                      | ◉                      | 35                            |                                                   |                                                                                       |
| Couriers Please        | ◉                      | ◉                      | 50                            |                                                   | `reference_1` and `reference_2` strings are joined                                    |
| DHL eCommerce          | ◉                      | ◉                      | 30                            | [label](/images/Carriers/label-ref-dhl-ecomm.png) | For domestic shipments, `reference_1` must be provided when `reference_2` is provided |
| DHL Germany            | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| DHL express            | ◉                      | ◉                      | 50                            | [label](/images/Carriers/label-ref-DHL.png)       |                                                                                       |
| Evri (formerly Hermes) | ◉                      | ◉                      | 20                            | [label](/images/Carriers/label-ref-evri.png)      |                                                                                       |
| FedEx                  | ◉                      | ◉                      | 50                            | [label](/images/Carriers/label-ref-fedex.png)     | See [note](#add-additional-details-to-a-fedex-label) below for more details           |
| GLS US                 | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| Lasership              | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| OnTrac                 | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| Swyft                  | ◉                      | ◉                      | 50                            |                                                   |                                                                                       |
| UDS                    | ◉                      | ◎                      | 50                            |                                                   |                                                                                       |
| UPS                    | ◉                      | ◉                      | 35                            | [label](/images/Carriers/label-ref-UPS.png)       |                                                                                       |
| USPS                   | ◉                      | ◉                      | 30                            | [label](/images/Carriers/label-ref-USPS.png)      |                                                                                       |
| Veho                   | ◉                      | ◎                      | 50                            | [label](/images/Carriers/label-ref-Veho.png)      |                                                                                       |

## Add reference details to a Shipment

To add reference details to a label for a supported carrier, use the fields `reference_1` and `reference_2` in the [Shipments Extras](/api-reference/shipments/list-all-shipments) object.

<Info>
  **note**

  For versions `2014-02-11` and `2016-10-25`, `reference_1` and `reference_2` are in the [Shipments](/api-concepts/api-change-log#shipments) object.
</Info>

Follow this example showing how to set reference fields.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d $'{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@shippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
      "extra": {
        "reference_1": "x999000",
        "reference_2": "Box no 5"
        },
      "async": false
  }'
```

## Add reference details to a Parcel

You can also define reference details in your parcel.
To add reference details to a label for a supported carrier, use the fields `reference_1` and `reference_2`
in the [Parcels Extras](/api-reference/parcels/list-all-parcels) object. This can be useful for [multi-piece shipments](/shipments/multi-piece-shipment) where you may choose to add a different reference to each label.

If you define both a parcel reference and a shipment reference, the parcel reference will be printed on your label (if your carrier supports it).

Follow this example showing how to set different references for each label in a multi-piece shipment.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-H 'Content-Type: application/json' \
-d $'{
  "address_from": {
        "name": "Mr Hippo",
        "street1": "965 Mission Street",
        "street2": "Suite 480",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
  },
  "address_to": {
      "name": "Mr Hippo",
      "street1": "2967 Filbert Dr",
      "street2": "APT 3",
      "city": "Walnut Creek",
      "state": "CA",
      "zip": "94598",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com"
  },
  "parcels": [{
    "weight": "8",
    "length": "9",
    "width": "3",
    "height": "8",
    "distance_unit": "in",
    "mass_unit": "lb",
    "extra": {
    "reference_1": "Parcel1 ref 1"
    }},
    {"weight": "8",
    "length": "9",
    "width": "3",
    "height": "8",
    "distance_unit": "in",
    "mass_unit": "lb",
    "extra": {
    "reference_2": "Parcel2 ref 2"
    }
  }],
  "extra": {
    "signature_required": "DIRECT",
    "reference_1": "Text shipment ref 1",
    "reference_2": "Text shipment ref 2"
  },
  "async": false
}'

```

The following are the resulting labels.

<img alt="sample multipiece label" />

## Add additional details to a FedEx label

For FedEx, Shippo supports more fields where you can add more information.
In the [Shipments Extras](/api-reference/shipments/list-all-shipments) object, you can use the following fields.

* `customer_reference`
* `po_number`
* `dept_number`
* `invoice_number`
* `rma_number`

Follow this example.

```shell cURL theme={null}
"extra": {
  "customer_reference": {
    "prefix": "REF#",
    "value": "my ref is 12234"
  },
  "po_number": {
    "prefix": "PO#",
    "value": "my number is 12234"
  },
  "dept_number": {
    "prefix": "DEPT#",
    "value": "dept number is 555"
  },
  "invoice_number": {
    "prefix": "INV#",
    "value": "my number is 5555"
  },
  "rma_number": {
    "prefix": "RMA#",
    "value": "rma number is 555"
  }
}

```

Note, these fields are available only on ZPL labels and support up to 11 characters for the prefix and up to 40 characters for the value.

* If `customer_reference` is used, reference\_1 will be ignored.
* If `po_number` is used, reference\_2 will be ignored.
* If `invoice_number` is used, for international shipments, `shipment.customs_declaration.invoice` will be ignored.

### Omnichannel shipping with FedEx

You can also customize FedEx’s label prefixes to meet those requirements for omnichannel shipping and label specific SOPs. Note, this applies to ZPL labels only.

The following example uses the ARN which is a unique shipment number assigned by Amazon to track the shipments and the LOAD number is a reference number for the shipment.

```shell cURL theme={null}
"extra": {
 "customer_reference": {
  "prefix": "ARN#",
  "value": "23256"
 },
 "po_number": {
  "prefix": "LOAD#",
  "value": "12234"
 },
 "dept_number": {
  "prefix": "DP",
  "value": "555"
 },
 "invoice_number": {
  "prefix": "invoice #",
  "value": "2999905"
 },
 "rma_number": {
  "prefix": "RMA#",
  "value": ""
 }
}

```

## Add additional details to a UPS label

You can add additional reference fields to UPS ZPL II labels. UPS allows a maximum of five reference fields for a single label.
In the [Shipments Extras](/api-reference/shipments/list-all-shipments) object, you can use the following fields.

* `accounts_receivable_customer_account`
* `appropriation_number`
* `bill_of_lading_number`
* `cod_number`
* `customer_reference`
* `dealer_order_number`
* `dept_number`
* `fda_product_code`
* `invoice_number`
* `manifest_number`
* `model_number`
* `part_number`
* `po_number`
* `production_code`
* `purchase_request_number`
* `rma_number`
* `salesperson_number`
* `serial_number`
* `store_number`
* `transaction_reference_number`

Follow this example.

```shell theme={null}
"extra": {
  "accounts_receivable_customer_account": {
    "prefix": "Accounts Rec:",
    "value": "",
    "ref_sort": 1
  },
  "appropriation_number": {
    "prefix": "Approp No.:",
    "value": "",
    "ref_sort": 2
  },
  "bill_of_lading_number": {
    "prefix": "Bill Lading:",
    "value": "",
    "ref_sort": 4
  },
  "cod_number": {
    "prefix": "COD:",
    "value": "",
    "ref_sort": 3
  },
  "customer_reference": {
    "prefix": "REF#",
    "value": "my ref is 12234",
    "ref_sort": 5
  }
```

Use `ref_sort` to define the order your references are printed on your label. If you choose to use `ref_sort`, you cannot use the same number more than once. If you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references.


# DHL eCommerce
Source: https://docs.goshippo.com/carriers/dh-le-commerce

Connect your DHL eCommerce account to Shippo and learn how to get rates and purchase shipping labels.

DHL eCommerce is an ideal carrier for third-party logistics businesses offering preferential rates for high-volume shippers.
Follow this guide to learn how to use your own DHL eCommerce account with Shippo.

<Info>
  **note**

  Before beginning this guide, you must have your own [DHL eCommerce account](https://www.dhl.com/global-en/home/our-divisions/ecommerce.html).
  Contact your DHL eCommerce account manager to get the [required parameters](/carriers/carrier-capabilities#dhl-ecommerce) to connect your account to Shippo.
</Info>

## Get a label from DHL eCommerce

### 1. Connect your account

Before you can get rates from DHL eCommerce, you must first add your [account details](/carriers/carrier-accounts#dhl-ecommerce).

**Request:**

```shell Connect your DHL eCommerce account theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "account_id": "string",
  "active": true,
  "carrier": "dhl_ecommerce",
  "account_id": "dhl_ecommerce", 
   "parameters": {
        "username": "HipposDontLie!", // DHL eCommerce client ID
        "password": "shipshippo", // DHL eCommerce client secret
        "pickup_no": "123123", // DHL eCommerce pickup number
        "facility_code": "23" // DHL eCommerce facility code
    }
  "test": false
}'
```

**Response:**

```json Connect your DHL eCommerce account response theme={null}
{
  "account_id": "****",
  "active": true,
  "carrier": "dhl_ecommerce",
  "parameters": {
        "username": "HipposDontLie!", // DHL eCommerce client ID
        "password": "shipshippo", // DHL eCommerce client secret
        "pickup_no": "123123", // DHL eCommerce pickup number
        "facility_code": "23" // DHL eCommerce facility code
  },
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "3579ad96a9534ea2bcc3487e703c98a1",
  "object_owner": "mrhippo@goshippo.com",
  "test": false
}
```

### 2. Get a rate from carrier

To get rates from your preferred carrier only, create a Shipment and use `carrier_accounts` with the object ID of your carrier.
The following example uses the object ID of the carrier added in [step 1](#1-connect-your-account).

<Info>
  **note**

  For international shipments, DHL eCommerces will not return a rate while in [test mode](/guides/testing). To get a rate, ensure you are using a live token and your carrier is not in test mode.
</Info>

**Request:**

```shell Get rates request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
        "name": "Mr Hippo",
        "street1": "965 Mission Street",
        "street2": "Suite 480",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
  },
  "address_to": {
      "name": "Mr Hippo",
      "street1": "2967 Filbert Dr",
      "street2": "APT 3",
      "city": "Walnut Creek",
      "state": "CA",
      "zip": "94598",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com"
  },
  "parcels": [{
    "weight": "8",
    "length": "9",
    "width": "3",
    "height": "8",
    "distance_unit": "in",
    "mass_unit": "lb"
  }],
  "extra": {
    "signature_required": "DIRECT"
  },
  "async": false,
  "carrier_accounts":["3579ad96a9534ea2bcc3487e703c98a1"]
}'
```

**Response:**

```json Get rates response theme={null}
{
    "carrier_accounts": [
        "3579ad96a9534ea2bcc3487e703c98a1"
    ],
    "object_created": "2024-02-09T15:51:51.386Z",
    "object_updated": "2024-02-09T15:51:51.386Z",
    "object_id": "ae70f937c08c45c59a0554dee6797270",
    "object_owner": "adrian.collins@goshippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "3f45f9e843834fcb9417d120f3a76943",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission Street",
        "validation_results": {},
        "street2": "Suite 480",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "886aac005c1a4abcb02c401c4f298d5b",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "2967 Filbert Dr",
        "validation_results": {},
        "street2": "APT 3",
        "street3": "",
        "city": "Walnut Creek",
        "state": "CA",
        "zip": "94598",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2024-02-09T15:51:51.340Z",
            "object_updated": "2024-02-09T15:51:51.397Z",
            "object_id": "0042019fad6a4a53ace731142a568048",
            "object_owner": "adrian.collins@goshippo.com",
            "template": null,
            "extra": {},
            "length": "9.0000",
            "width": "8.0000",
            "height": "3.0000",
            "distance_unit": "in",
            "weight": "8.0000",
            "mass_unit": "lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2024-02-09T15:51:51.340Z",
    "address_return": {
        "object_id": "3f45f9e843834fcb9417d120f3a76943",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission Street",
        "validation_results": {},
        "street2": "Suite 480",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "customs_declaration": null,
    "extra": {
        "signature_required": "DIRECT"
    },
    "rates": [
        {
            "object_created": "2024-02-09T15:51:52.407Z",
            "object_id": "b94689b62e8c4fda9e37fd8d61c8ebd4",
            "object_owner": "adrian.collins@goshippo.com",
            "shipment": "ae70f937c08c45c59a0554dee6797270",
            "attributes": [
                "BESTVALUE",
                "CHEAPEST"
            ],
            "amount": "13.17",
            "currency": "USD",
            "amount_local": "13.17",
            "currency_local": "USD",
            "provider": "DHL eCommerce",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/DHL_ecommerce.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/DHL_ecommerce.png",
            "servicelevel": {
                "name": "Parcels Ground",
                "token": "dhl_ecommerce_parcels_ground",
                "terms": ""
            },
            "estimated_days": 5,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
            "test": true,
            "zone": "USPS08"
        }
    ],
    "messages": [],
    "metadata": "",
    "test": true,
    "order": null
}
},
```

### 3. Purchase label

To purchase a label, create a Transaction using the object ID of your preferred Rate.

**Request:**

```shell Purchase label  theme={null}
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
  "async": false
}'
```

**Response:**

```json Purchase label response theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2024-02-09T15:54:15.760Z",
    "object_updated": "2024-02-09T15:54:17.003Z",
    "object_id": "162b77609c574d499daa9c63d813a845",
    "object_owner": "adrian.collins@goshippo.com",
    "test": true,
    "rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
    "tracking_number": "420945989261299999999900348426",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://webtrack.dhlglobalmail.com/?trackingnumber=420945989261299999999900348426",
    "label_url": "https://deliver.goshippo.com/162b77609c574d499daa9c63d813a845.pdf?Expires=1739030056&Signature=Qzu1k~x5dVgmJqX89t1~EjB4p6jeuorKluEaWLh3mBfpz4OesKeugBBw4KywxNdcA6IPNPQcygEtf8AHdQjWt8MBIintLYBRTy0d7cBZNiiw5NOAGvAu5bfG0etnfC9C0alow2DdxJAhs7UhaemIo4~zWBP2nbQmssycaYwcDAGMHqQjBwjEd5-qTpGf0~Xs1az-xFv5eAjibaq47fCrWDo8Ms7ijQXlbOwtLeEYX-dqtQDpNNzBfCpDbRmGLJrz4t3xsDBcIutf78aZQMmwTb~KsYdESt~aKNT65Nz4~4BTj-JwWWjWFykJHZXzTfpc~SI0OLOMbEXU3VNlnM0MTA__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ",
    "commercial_invoice_url": null,
    "messages": [],
    "order": null,
    "metadata": "",
    "parcel": "0042019fad6a4a53ace731142a568048",
    "billing": {
        "payments": []
    },
    "qr_code_url": null
}
```

### 4. Manifest

DHL eCommerce requires that every label generated is added to a manifest. If you do not create a manifest, your labels will remain on hold. For more information on manifests, see our guide on [Manifests and SCAN forms](/manifests-and-pickups/manifest-and-scan-forms).

**Request:**

```shell Create manifest request theme={null}
curl --location 'https://api.goshippo.com/manifests/' \
--header 'Content-Type: application/json' \
--header 'Authorization: ShippoToken <API_token>' \
--data '{
  "address_from": {
        "name": "Mr Hippo",
        "street1": "965 Mission Street",
        "street2": "Suite 480",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
  },
  "carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
  "shipment_date": "2024-02-09T15:54:17.003Z",
  "transactions": ["162b77609c574d499daa9c63d813a845","90909er0erfs343sdsd45sdsd45rtg"],
  "async": false
}'

```

**Response:**

```json Create manifest response theme={null}
{
  "object_created": "2024-02-09T16:13:22.583Z",
  "object_updated": "2024-02-09T16:13:24.634Z",
  "object_id": "e830855fbc8e42d7b67b0e00c7592d02",
  "object_owner": "adrian.collins@goshippo.com",
  "status": "SUCCESS",
  "errors": [],
  "provider": "dhl_ecommerce",
  "shipment_date": "2024-02-09T15:54:17.003Z",
  "address_from": "5066d8cc1a0849ea9a08da274e42f54b",
  "documents": [
    "https://deliver.goshippo.com/e830855fbc8e42d7b67b0e00c7592d02_USLAX1_53219514020916132300.pdf?Expires=1739031204&Signature=X1s6F1H~WGG5qRhOYEPfr3ISuvD0hXXwfKw-npyZHU6~7wzZPw27rIBVUuCtTyd4n~AP8PNu7vq8dUIdvOLhcgJIO7dCr1fnXmLb~C1ufo3bJfD4uN0wcH883Os0pETbjz0Dd~66AsFcgh58FsexSn0U7jIe5F~7vKaWQJkGd4jXX~Lo7fMtIWtfVNlW6KLzr-L2fD5wvB2x8IkPlzbH8t6t4j3f4GXqebtGibcD8JLDuqsYUq3NpnS4Z0~-aamp560SeD0vbuqwQPhMFo1Fo8Hblmw7c4ZiC~0A03D5vb2X2xnl0EhuqcT4hk~FTf-sGKIj~EJnFi5QlLZXN1ZupA__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ"
  ],
  "carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
  "transactions": ["162b77609c574d499daa9c63d813a845","90909er0erfs343sdsd45sdsd45rtg"]
}
```

## Hazmat / Dangerous goods

Before attempting to ship hazardous or dangerous goods with DHL eCommerce, we recommend reviewing the  [Hazardous Goods and Unacceptable Shipments](https://www.dhl.com/us-en/home/ecommerce/business-help-center/hazardous-goods-and-unacceptable-shipments.html) guide.

To declare hazardous or dangerous goods for DHL eCommerce, use `dangerous_goods_code` in `Extras` when creating a Shipment.

Follow this example to declare dangerous goods in your Shipment.

```shell theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
        "name": "Mr Hippo",
        "street1": "965 Mission Street",
        "street2": "Suite 480",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
  },
  "address_to": {
      "name": "Mr Hippo",
      "street1": "2967 Filbert Dr",
      "street2": "APT 3",
      "city": "Walnut Creek",
      "state": "CA",
      "zip": "94598",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com"
  },
  "parcels": [{
    "weight": "8",
    "length": "9",
    "width": "3",
    "height": "8",
    "distance_unit": "in",
    "mass_unit": "lb"
  }],
  "extra": {
    "signature_required": "DIRECT",
    "dangerous_goods_code": "02"
  },
  "async": false,
  "carrier_accounts":["3579ad96a9534ea2bcc3487e703c98a1"]
}'

```

To learn more about DHL eCommerce dangerous goods codes, refer to [DHL dangerous goods codes](#dhl-dangerous-goods-codes).

## Restrictions

### US Territories

DHL eCommerce supports shipments from US Territories to the US and from the US to the US Territories.
DHL eCommerce does not support shipments between US Territories.

### APO and FPO

APO and FPO are abbreviations used by the US Military Postal Service and Army Post Office.
DHL eCommerce does not support shipments to, from, or between APO and FPO addresses.

## DHL eCommerce Service level tokens

To support our customers who have integrated with Shippo using legacy DHL eCommerce tokens, we have maintained some legacy token naming. Refer to thi stable for more information.

| Token                                           | Shippo Service name              | DHL Service name                             |
| ----------------------------------------------- | -------------------------------- | -------------------------------------------- |
| dhl\_ecommerce\_parcel\_international\_direct   | Parcel International Direct      | DHL Parcel International Direct              |
| dhl\_ecommerce\_parcels\_expedited\_max         | Parcels Expedited Max            | DHL SmartMail Parcel Expedited Max           |
| dhl\_ecommerce\_bpm\_ground                     | Bounded Printed Matter Ground    | DHL SmartMail Bound Printed Matter Ground    |
| dhl\_ecommerce\_parcels\_expedited              | Parcels Expedited                | DHL SmartMail Parcel Expedited               |
| dhl\_ecommerce\_parcels\_ground                 | Parcels Ground                   | DHL SmartMail Parcel Ground                  |
| dhl\_ecommerce\_parcel\_international\_standard | Parcel International Standard    | DHL Parcel International Standard            |
| dhl\_ecommerce\_bpm\_expedited                  | Bounded Printed Matter Expedited | DHL SmartMail Bound Printed Matter Expedited |
| dhl\_ecommerce\_globalmail\_packet\_priority    | GlobalMail Packet Priority       | DHL GlobalMail Packet Priority               |
| dhl\_ecommerce\_easy\_return\_light             | Easy Return Light                | DHL SmartMail Parcel Return Light            |
| dhl\_ecommerce\_easy\_return\_plus              | Easy Return Plus                 | DHL SmartMail Parcel Return Plus             |
| dhl\_ecommerce\_marketing\_parcel\_expedited    | Marketing Parcel Expedited [^1]  | DHL SmartMail Marketing Parcel Expedited     |
| dhl\_ecommerce\_globalmail\_packet\_ipa         | GlobalMail Packet IPA [^1]       | DHL GlobalMail Packet- IPA                   |
| dhl\_ecommerce\_marketing\_parcel\_ground       | Marketing Parcel Ground [^1]     | DHL SmartMail Marketing Parcel Ground        |
| dhl\_ecommerce\_globalmail\_packet\_plus        | GlobalMail Packet Plus [^1]      | DHL Packet Plus International                |

[^1]: These service levels are only available to legacy users. New users will not see these service levels.

## DHL eCommerce reference fields

Refer to our [carrier reference fields](/carriers/carrier-reference-fields#supported-carriers) guide for details on reference fields used by DHL eCommerce.
To pass billing reference information to DHL eCommerce through the Shippo API, use `reference_2`.

## DHL dangerous goods codes

### Domestic shipments

| Category Code | Description                                                     | Max. Weight |
| ------------- | --------------------------------------------------------------- | ----------- |
| 01            | Lithium Metal / Alloy Batteries Contained in Equipment          | 11 lbs      |
| 02            | Lithium Metal / Alloy Batteries Packed with Equipment           | 11 lbs      |
| 03            | Lithium Metal / Alloy Batteries Stand-Alone                     | 5 lbs       |
| 04            | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 11 lbs      |
| 05            | Lithium-ion or Lithium Polymer Batteries with Equipment         | 11 lbs      |
| 06            | Lithium-ion or Lithium Polymer Batteries Stand-Alone            | 5 lbs       |
| 08            | Limited Quantity / ORM-D                                        | 25 lbs      |
| 09            | Small Quantity Provision                                        | 25 lbs      |

### International shipments

| Category Code | Description                                                     | Max. Weight | Restrictions |
| ------------- | --------------------------------------------------------------- | ----------- | ------------ |
| 01            | Lithium Metal / Alloy Batteries Contained in Equipment          | 4.4 lbs     | Canada Only  |
| 01            | Lithium Metal / Alloy Batteries Contained in Equipment          | 11 lbs      | Canada Only  |
| 02            | Lithium Metal / Alloy Batteries Packed with Equipment           | 11 lbs      | Canada Only  |
| 03            | Lithium Metal / Alloy Batteries Stand Alone                     | 5 lbs       | Canada Only  |
| 04            | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 4.4 lbs     | Canada Only  |
| 04            | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 11 lbs      | Canada Only  |
| 05            | Lithium-ion or Lithium Polymer Batteries Packed with Equipment  | 11 lbs      | Canada Only  |
| 06            | Lithium-ion or Lithium Polymer Batteries Stand Alone            | 5 lbs       | Canada Only  |
| 40            | Limited quantities                                              | 25 lbs      | Canada Only  |

For more details on category codes, refer to the [DHL eCommerce references](https://api.dhlecs.com/docs/references) guide.


# ePost Global
Source: https://docs.goshippo.com/carriers/e-post-global

Learn about ePost Global requirements for including line items in the parcel object for domestic shipment rates and labels.

Special requirements for ePost Global domestic shipments

API users attempting to retrieve rates or purchase labels for ePost Global domestic shipments must specify an additional line\_items field within the Parcel object. Below is a sample parcel payload with line\_items specified:

```json theme={null}
{
	"length": 5,
	"width": 5,
	"height": 5,
	"distance_unit": "in",
	"weight": 3,
	"mass_unit": "lb",
	"line_items": [
  		{
  	"manufacture_country": "US",
    	"quantity": 1,
    	"weight_unit": "lb",
    	"weight": 1,
    	"title": "Jeans",
    	"amount": "30",
    	"sku": "HM-112",
    	"currency": "USD"
  	},
  	...
	]
  }
```

Create a new shipment as usual with the parcel to obtain a list of rate objects or use single call label creation to purchase labels. Note ePost Global international shipments do not require parcel line\_items.


# Get your Carrier Account Details
Source: https://docs.goshippo.com/carriers/integration-guides/apg/create-an-account

Add your APG carrier account credentials to Shippo so you can generate shipping rates and create labels.

To use the carrier APG with Shippo, you must [use your own account](#use-your-own-carrier-account) and share your account details with Shippo.

## Use your own carrier account

Follow this guide to add your APG account to Shippo. After adding your account, Shippo can use your account details for generating shipping rates and creating labels.
This step requires you to have your APG account id and password.

This step should only be completed once. When you have created your carrier account, you can use the carrier `object_id` to reference your carrier.

### HTTP Method

POST

### URL

```
https://api.goshippo.com/carrier_accounts/
```

### Request Payload

| Parameter     | Description                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| carrier\*     | `apg`                                                                                                                                                |
| account\_id\* | A unique identifier for the account which cannot be changed later. Used only for internal purposes. This should be a username provided by APG        |
| parameters\*  | parameters is an array of additional parameters for the account, such as password or token. Check [APG parameters](#account_params) for more details |
| active        | Set to `true` to enable account. Set to `false` to disable account.                                                                                  |
| test          | Set to `true` if you want to set the account in test mode. Using test mode you can generate test labels without incurring a charge                   |

Note: Parameters with an \* are mandatory

### <a name="account_params" /> APG Account Parameters

| Parameter     | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| account\_id\* | Key to access the API. A string value APG assigns to each client. |
| password\*    | Key to access the API. A string value APG assigns to each client. |
| sender\_code  | Code assigned by APG to to each client. Example: “sti.us.client”  |

### Response Code

201

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "carrier": "apg",
   "object_owner": "billable-user@shippo.com",
   "account_id": "EXAMPLE_UNIQUE_ACCOUNT_ID",    
   "parameters": {
       "account_id": "ACCOUNT_ID_PROVIDED_BY_APG_SHOULD_BE_HERE",  
       "password": "PASSWORD_PROVIDED_BY_APG_SHOULD_BE_HERE", 
       "sender_code": "STI.US.EXAMPLE" 
   },
   "test": false,   //true if it is test account
   "active": true,
   "is_shippo_account": false,
   "metadata": "Metadata_example for APG Account",
   "carrier_name": "APG"
}'

```

#### Response Sample

```json theme={null}
 "carrier": "apg",
           "object_id": "2edac0dddcfc4416b2708cc10b2d11e0",
           "object_owner": "nataliya_eng@shippo.com",
           "account_id": "UNIQUE_ACCOUNT_ID_HERE",
           "parameters": {
               "password": "******",
               "account_id": "shippo",
               "sender_code": "sti.us.EXAMPLE"
           },
           "test": false,
           "active": true,
           "is_shippo_account": false,
           "metadata": "APG - Shippo Account - test",
           "carrier_name": "APG",
           "carrier_images": {
               "200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/apg.png",
               "75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/apg.png"
           }


```

Once you have retrieved the `object_id` for your carrier, proceed to [Step 2: Create shipment](/carriers/integration-guides/apg/create-shipment).


# Create shipment
Source: https://docs.goshippo.com/carriers/integration-guides/apg/create-shipment

Create an APG shipment with addresses, parcel details, and customs declarations to generate shipping rates.

The second step is to create a shipment. The shipment includes all the details about the item you are shipping including

* the "from" and "to" addresses
* the parcel details
* extra parameters
* customs declaration, that are required for international shipments

Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you. In these examples, you will see rates from APG but you can also generate rates from other carriers using the carrier\_accounts parameter.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/shipments/
```

## Request Payload

| Parameter              | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_from\*        | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                    |
| address\_to\*          | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                    |
| parcels\*              | [Refer to the Parcel object](#parcel)                                                                                                                                                                                                                                                                                                                                                                                      |
| extra                  | [Refer to the Extra object](#extra)                                                                                                                                                                                                                                                                                                                                                                                        |
| customs\_declaration\* | [Refer to the Customs declaration object](#customs_declaration). <br />Required for international shipments                                                                                                                                                                                                                                                                                                                |
| carrier\_accounts      | An array of object\_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object\_id is available when an account is created. See [carrier account response sample](#carrier-acc-resp-ex).<br />If no carrier account object\_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the 'active' field set. |
| label\_file\_type\*    | Allowed values: `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PDF_SINGLE_8X11`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII`                                                                                                                                                                                                                                                                                           |
| metadata               | Possible to use to define customer ID                                                                                                                                                                                                                                                                                                                                                                                      |
| async                  | If set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.                                                                                                                                                                                                                                    |

Note: Parameters with an \* are mandatory

## Objects

### <a name="address" /> Address

| Parameter       | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| Name\*          | First and Last name of the addressee                                         |
| Company         | Company Name (if applicable)                                                 |
| Street1\*       | First street line, 35 character limit. Usually street number and street name |
| Street2         | Second street line, 35 character limit                                       |
| City\*          | Name of a city                                                               |
| Zip\*           | Postal code of an address                                                    |
| State\*         | State/Province values are required for shipments from/to the US.             |
| Country\*       | ISO 2 country code                                                           |
| phone           | Phone number of the addressee                                                |
| email           | E-mail address of the contact person, RFC3696/5321-compliant                 |
| is\_residential | `true`(if address is residential) or `false` if not.                         |

### <a name="parcel" /> Parcel

| Parameter             | Description                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| length\*              | Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted                                                                 |
| width\*               | Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted                                                                  |
| height\*              | Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted                                                                 |
| distance\_unit\*      | "cm"<br /> "in"<br /> "ft"<br /> "mm"<br /> "m"<br />  "yd"                                                                                                              |
| weight\*              | Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted                                                                 |
| mass\_unit\*          | "g"<br /> "oz"<br /> "lb"<br />  "kg"                                                                                                                                    |
| line\_items\*         | Array of object for one or several line items. This section contains the line items’ details that were packed in the relevant parcel. See [line items](#lineitem) object |
| custom\_declaration\* | Custom declaration support. See [customs declaration](#customs_declaration) object                                                                                       |

### <a name="lineitem" /> Line Items

| Parameter              | Description                                         |
| ---------------------- | --------------------------------------------------- |
| title\*                | Description of product                              |
| variant\_title         | Additional description                              |
| SKU\*                  | Product’s stock keeping unit                        |
| hs\_code\*             | hs\_code                                            |
| quantity               | quantity                                            |
| amount\*               | Amount                                              |
| currency\*             | Currency                                            |
| weight\_unit\*         | Weight unit for this item’s type                    |
| manufacture\_country\* | [ISO 2 country code](https://www.iso.org/home.html) |

### <a name="customs_declaration" />  Customs Declaration

<Info>
  **Note**

  * If shipping to AU or NZ using APG, you must pass an `ARN` on the tax identifiers using `Exporter_identification.tax_id` in your customs declaration.
  * If shipping to an EU country using APG, you must pass an `IOSS` value on the tax identifiers using `Exporter_identification.tax_id` in your customs declaration.
</Info>

| Parameter                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contents\_type           | Type of goods of the shipment. <br />Possible values: <br />`DOCUMENTS`<br />`GIFT`<br />`SAMPLE`<br />`MERCHANDISE`<br />`HUMANITARIAN_DONATION`<br />`RETURN_MERCHANDISE` <br />`OTHER`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| certify                  | Expresses that the certify\_signer has provided all information of this customs declaration truthfully. Boolean value: `true` or `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| certify\_signer          | Name of the person who created the customs declaration and is responsible for the validity of all information provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| incoterm                 | The incoterm reference of the shipment. <br />Possible values: <br /> `DDU` (For shipments where you expected to use `DAP`, use `DDU` instead) <br /> `DDP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| is\_vat\_collected       | Indicates whether the shipment's destination VAT has been collected. Required for AU/NZ destinations if exporter\_indentification.number is not empty and exporter\_indentification.tax\_id = “ARN” Boolean value: true or false.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Exporter\_identification | Exporter\_identification should be here as number and tax\_id. <br /> `number` - means tax identification number.<br /> `tax_id` - type of tax identification.<br /><br /> Possible types of tax\_id: <br /> `EIN` - Employer Identification Number, also known as a Federal Tax Identification Number. <br />`VAT` - Value Added Tax identification number.<br /> `IOSS` - Import One-Stop Shop <br /> `ARN` - Australian Taxation Office Reference Number <br /><br />Example:<br />                "exporter\_identification": <br /> <br />               "tax\_id":   <br />                  "type": "IOSS",      <br />              "number": "TAXNUMBER12345"        <br />              <br />       <br /> |
| items\*                  | Array of Customs Items object\_ids<br /> Example:<br />       <br />              "description": "shirt",      <br />              "quantity": 1,    <br />                "net\_weight": "1",        <br />            "mass\_unit": "oz",           <br />         "value\_amount": "10",          <br />          "value\_currency": "USD",         <br />           "origin\_country": "US",          <br />          "tariff\_number": "",          <br />          "metadata": "ts mi"       <br />                                                                                                                                                                                                             |

### <a name="extra" /> Extra Details

| Parameter               | Description                                                                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| extra: reference\_1     | APG OrderNo.  The primary shipment reference used by your organization. It can be the sales order number, the shipment number or any other delivery identification. Optional text to be printed on the shipping label. Up to 50 characters |
| extra: carrier\_hub\_id | Identifies the carrier injection site (APG HAWBOrigin). You should only specify this for shipments originating from USA. The following codes are supported hub IDs: `JFK`, `LAX`, `MIA`, `ORD`, `ATL`.                                     |

## Response Code

201

## Examples

### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "object_purpose": "PURCHASE",
   "shipment_date": "2022-12-10T23:59:59Z",
   "address_from": {
       "object_purpose": "PURCHASE",
       "name": "Shipping Manager",
       "company": "Shippo",
       "street1": "4727 W 1st St",
       "street2": "",
       "city": "New York",
       "state": "NY",
       "zip": "10005",
       "country": "US",
       "phone": "12028642186",
       "email": "nataliya_eng@shippo.com",
       "is_residential": false
   },
   "address_to": {
  "object_purpose": "PURCHASE",
       "name": "Nata Lee",
       "company": "Shipper -2 , Inc.",
       "street1": "1720 S Grand Ave",
       "city": "Sydney",
       "state": "VIC",
       "zip": "3026",
       "country": "AU",
       "phone": "+1 666 147 2589",
       "email": "nata@gmail.com",
       "metadata": "",
       "is_residential": true
   },
   "parcels": {
       "length": "10",
       "width": "8",
       "height": "10",
       "distance_unit": "cm",
       "weight": 2,
       "mass_unit": "kg",
       "line_items": [
           {
               "title": "Hippo Magazines",
               "variant_title": "June edition",
               "sku": "HM-123",
               "hs_code": "2123",
               "quantity": 1,
               "amount": "12.10",
               "currency": "USD",
               "weight_unit": "kg",
               "manufacture_country": "US"
           },
           {
               "title": "Hippo Magazines -2",
               "variant_title": "June edition",
               "sku": "HM-1234",
               "hs_code": "21234",
               "quantity": 1,
               "amount": "15.10",
               "currency": "USD",
  "weight_unit": "kg",
               "manufacture_country": "US"
           }
       ]
   },
   "customs_declaration": {
       "contents_type": "MERCHANDISE",
       "non_delivery_option": "ABANDON",
       "certify": true,
       "certify_signer": "Test Certifier",
       "incoterm": "DDP",
       "is_vat_collected": "",
       "exporter_identification": {
           "tax_id": {
               "type": "ARN",
               "number": "TAXNUMBER12345"
           }
       },
       "items": [
           {
               "description": "shirt",
               "quantity": 1,
               "net_weight": "1",
               "mass_unit": "oz",
               "value_amount": "10",
               "value_currency": "USD",
               "origin_country": "US",
               "tariff_number": "",
               "metadata": "ts mi"
           }
       ]
   },
   "extra": {
       "reference_1": "1234567890",
       "carrier_hub_id": "ORD"
   },
   "metadata": "Customer ID 123456",
   "async": false,
   "label_file_type": "PDF",
   "carrier_accounts": [
     "{{APG_ACC}}"
   ]
}’


```

### <a name="carrier-acc-resp-ex" />Response Sample

```json theme={null}
 {
    "carrier_accounts": [
        "2edac0dddcfc4416b2708cc10b2d11e0"
    ],
    "object_created": "2022-12-09T13:27:24.058Z",
    "object_updated": "2022-12-09T13:27:24.058Z",
    "object_id": "f2f1bf3f4a004ce2b609f7c19251b15d",
    "object_owner": "nataliya_eng@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "8d50f611519e4efb89934cc3ee1905c0",
        "is_complete": true,
        "name": "Shipping Manager",
        "company": "",
        "street_no": "",
        "street1": "4727 W 1st St",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "New York",
        "state": "NY",
        "zip": "10005",
        "country": "US",
        "phone": "12028642186",
        "email": "nataliya_eng@shippo.com",
        "is_residential": false,
        "test": true
    },
    "address_to": {
        "object_id": "36e3b76eece54237aa7a1b33bc6b834b",
        "is_complete": true,
        "name": "Nata Lee",
        "company": "Shipper -2 , Inc.",
        "street_no": "",
        "street1": "1720 S Grand Ave",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "Sydney",
        "state": "VIC",
  "zip": "3026",
        "country": "AU",
        "phone": "0016661472589",
        "email": "nata@gmail.com",
        "is_residential": true,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-12-09T13:27:23.751Z",
            "object_updated": "2022-12-09T13:27:24.413Z",
            "object_id": "9510a3eeb03245a4b53703019894b323",
            "object_owner": "nataliya_eng@shippo.com",
            "template": null,
            "extra": {},
            "length": "10.0000",
            "width": "10.0000",
            "height": "8.0000",
            "distance_unit": "cm",
            "weight": "2.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [
                "ed20bbd90c4248cd9ab3ea4836a9d407",
                "964b6b076b034b64b911cb18afbb489a"
            ],
            "test": true
        }
    ],
    "shipment_date": "2022-12-10T23:59:59Z",
    "address_return": {
        "object_id": "8d50f611519e4efb89934cc3ee1905c0",
        "is_complete": true,
        "name": "Shipping Manager",
        "company": "",
        "street_no": "",
        "street1": "4727 W 1st St",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "New York",
        "state": "NY",
        "zip": "10005",
        "country": "US",
        "phone": "12028642186",
        "email": "nataliya_eng@shippo.com",
        "is_residential": false,
"test": true
    },
    "alternate_address_to": null,
    "customs_declaration": {
        "object_created": "2022-12-09T13:27:23.959Z",
        "object_updated": "2022-12-09T13:27:23.959Z",
        "object_id": "66b6b7ee811b44a7abddaa4307181afd",
        "object_owner": "nataliya_eng@shippo.com",
        "object_state": "VALID",
        "address_importer": null,
        "certify_signer": "Test Certifier",
        "certify": true,
        "items": [
            "249fa7da308d4e41b2af4fed32368d81"
        ],
        "non_delivery_option": "ABANDON",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "notes": "",
        "eel_pfc": "",
        "aes_itn": "",
        "disclaimer": "",
        "incoterm": "DDP",
        "metadata": "",
        "test": true,
        "duties_payor": null,
        "b13a_filing_option": "",
        "b13a_number": "",
        "invoiced_charges": null,
        "exporter_identification": {
            "tax_id": {
                "type": "ARN",
                "number": "TAXNUMBER12345"
            }
        },
        "is_vat_collected": false
    },
    "extra": {
        "reference_1": "1234567890",
        "carrier_hub_id": "ORD"
    },
    "rates": [
        {
            "object_created": "2022-12-09T13:27:26.219Z",
   "object_id": "faef46ec7aa041adb700d288eb75df9d",
            "object_owner": "nataliya_eng@shippo.com",
            "shipment": "f2f1bf3f4a004ce2b609f7c19251b15d",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "6.10",
            "currency": "USD",
            "amount_local": "8.99",
            "currency_local": "AUD",
            "provider": "APG",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/apg.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/apg.png",
            "servicelevel": {
                "name": "ePacket Plus",
                "token": "epacket_plus",
                "terms": "Only delivery tracking in destination country",
                "extended_token": "epacket_plus",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0",
            "test": true,
            "zone": null
        },
        {
            "object_created": "2022-12-09T13:27:26.219Z",
            "object_id": "afd962698779489d9210cc7ed0ea0f4a",
            "object_owner": "nataliya_eng@shippo.com",
            "shipment": "f2f1bf3f4a004ce2b609f7c19251b15d",
            "attributes": [],
            "amount": "9.76",
            "currency": "USD",
            "amount_local": "14.38",
            "currency_local": "AUD",
            "provider": "APG",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/apg.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/apg.png",
            "servicelevel": {
                "name": "eParcel premium",
                "token": "eparcel_premium",
                "terms": "",
                "extended_token": "eparcel_premium",
                "parent_servicelevel": null
                            },
                            "estimated_days": null,
                            "arrives_by": null,
                            "duration_terms": "",
                            "messages": [],
                            "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0",
                            "test": true,
                            "zone": null
                        }
                    ],
                    "messages": [],
                    "metadata": "Customer ID 123456",
                    "test": true,
                    "order": null
                }

```


# Multi-parcel support
Source: https://docs.goshippo.com/carriers/integration-guides/apg/multiparcel-support

Create multi-parcel shipments with APG using the one-step or two-step label creation process in Shippo.

This is the method when we create several parcels in shipment.
Shippo supports creating multi-parcel shipments for both one step label and 2-steps label creation. The example shown here uses one step label creation.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/transactions/
```

## Request Payload

| Parameter         | Description                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| parcels\*         | Array of parcels.<br />[Example with 2 parcels](#2parcel-ex)                                                                                                              |
| label\_file\_type | Allowed values:<br />`PDF`<br />`PDF_A4`<br />`PDF_A6`<br />`PDF_4x6`<br />`PDF_4x8`<br />`PDF_SINGLE_8X11`<br />`PDF_2.3x7.5`<br />`PNG`<br />`PNG_2.3x7.5`<br />`ZPLII` |

### <a name="2parcel-ex" />Example with 2 parcels

```json theme={null}
"parcels": [

       {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               },
               {
                   "title": "Hippo Magazines -2",
                   "variant_title": "June edition",
                   "sku": "HM-1234",
                   "hs_code": "21234",
                   "quantity": 1,
                   "amount": "15.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       {
           "length": "10",
           "width": "5",
           "height": "8",
           "distance_unit": "cm",
           "weight": 3,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines - 2",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       }
   ],
```

## Response Code

201 Created

## Request Sample

### One step label API with 2 parcels

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
   {
   "shipment": {
       "object_purpose": "PURCHASE",
       "address_from": {
           "object_purpose": "PURCHASE",
           "name": "Shipping Mgr",
           "company": "Shippo",
           "street1": "4727 W 1st St",
           "street2": "",
           "city": "New York",
           "state": "NY",
           "zip": "10005",
           "country": "US",
           "phone": "12028642186",
           "email": "nataliya_eng@shippo.com",
           "is_residential": false
       },
       "address_to": {
           "object_purpose": "PURCHASE",
           "name": "Nata Lee",
           "street1": "1720 S Grand Ave",
           "city": "Sydney",
           "state": "VIC",
           "zip": "3026",
           "country": "AU",
           "phone": "+1 666 147 2589",
           "email": "nata@gmail.com",
           "metadata": "",
           "is_residential": true
       },
       "parcels": [
       {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               },
               {
                   "title": "Hippo Magazines -2",
                   "variant_title": "June edition",
                   "sku": "HM-1234",
                   "hs_code": "21234",
                   "quantity": 1,
                   "amount": "15.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       {
           "length": "10",
           "width": "5",
           "height": "8",
           "distance_unit": "cm",
           "weight": 3,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines - 2",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       }
   ],
       "customs_declaration": {
           "contents_type": "MERCHANDISE",
           "certify": true,
           "certify_signer": "Test Certifier",
           "incoterm": "DDP",
           "is_vat_collected": "paid",
           "exporter_identification": {
               "tax_id": {
                   "type": "IOSS",
                   "number": "TAXNUMBER12345"
               }
           },
           "items": [
               {
                   "description": "shirt",
                   "quantity": 1,
                   "net_weight": "1",
                   "mass_unit": "oz",
                   "value_amount": "10",
                   "value_currency": "USD",
                   "origin_country": "US",
                   "tariff_number": "",
                   "metadata": "ts mi"
               }
           ]
       },
       "extra": {
           "reference_1": "123456780",
           "carrier_hub_id": "ORD"
       },
       "metadata": "Customer ID 123456",
       "async": false
   },
   "label_file_type": "PDF",
   "carrier_account": "{{APG_ACC}}",
   "servicelevel_token": "eparcel_premium"
}
}'

```

## Response Sample

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-12-15T10:17:53.981Z",
   "object_updated": "2022-12-15T10:18:05.066Z",
   "object_id": "8c38d895e31c49c0b01106437f3d6375",
   "object_owner": "nataliya_eng@shippo.com",
   "test": true,
   "rate": {
       "object_id": "d576659148574262b540c1d955def30a",
       "amount": "22.32",
       "currency": "USD",
       "amount_local": "32.95",
       "currency_local": "AUD",
       "provider": "APG",
       "servicelevel_name": "eParcel premium",
       "servicelevel_token": "eparcel_premium",
       "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0"
   },
   "tracking_number": "2908932",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "https://apgecommerce.com/?page_id=18102908932",
   "label_url": "https://dev-qa-deliver.shippodev.com/8c38d895e31c49c0b01106437f3d6375.pdf?Expires=1702635483&Signature=cx-F9Zon1PeX8zn2v3kSUhETX1uNmQeLDmL4rR2td42mdnOabmUSj-Hi0AiQ1ea3yjPgmLu6oG-nOb7yOa36jsuKaF9RjB22pzpMUVi7PspI8Av~kYRSCAjd4BFgeOI8qNdmSlp5XSuj0LLs1iMU5DnqoSQQZ-SdnHEYfB1DsBOaJKz32S16Zr-pWTAMHxD2JCCiRjRiudpIdno7W4kFJ8aBBPp60DTOyFjj8RQAbNyDtOe3TKngSx6ZmTmzRLZ2RknyU-bJOdA6hJOISgwoF6vcHMtvffr1wIgtzbkC5m7vn8dAsoyozdbAV1bsU-dal~fWDtjBfrjVgWrPFgf~IA__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
   "commercial_invoice_url": "https://dev-qa-deliver.shippodev.com/ci_8c38d895e31c49c0b01106437f3d6375.pdf?Expires=1702635485&Signature=kF3QO30vkFsiEmO0mdOy38atSo~SXugd3GkOns~6LxwrnZB5c3wewkO6gKdfIktQf4EejnYp~4cRpWm0Z5rN8FRwD6f5QSF54R~4ZrURq3c3JQ4YjfO7Jba7H-6HAiAP9XzGsQ8rPREz2ckrSvGSF-0fycmEgh5QngF~H9V9r7wf1SDiBM7AOVfCb0zYJeqHrPEwsPy7YOOnXzn~vl7KCAc48lI08yuxeUNcOo1mr0yCJfNaoqOwYVlyd8dGNXsXu~76lP5TZvoMLHshjQYFPr2HguL6ChgEUnFwrks7wjC2btRVDGcBlcnQWi0ndCX56Aag9zqd3ubOHiPQ1pI7fg__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "ac06b161f77f46fc8f2c0edca47251b3",
   "billing": {
       "payments": []
   },
   "qr_code_url": null
}


```


# Purchase label
Source: https://docs.goshippo.com/carriers/integration-guides/apg/purchase-label

Purchase an APG shipping label from a created shipment or generate one in a single API call using Shippo.

The final step is to purchase the shipment. This will generate your shipping label.

There are two ways to purchase a shipment.

1. You can [purchase the shipment object](#purchase-from-created-shipment) you created in the last step. This is useful when you want to find the best rate and service level for your shipment.
2. You can purchase a label without a [shipment object in a single call](#purchase-label-in-one-call). This is useful when you what to immediately create your label.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/transactions/
```

## Purchase from created Shipment

This is a flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided `rate`.

### Request Payload

| Parameter         | Description                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| rate\*            | ‘object\_id’ of the rate object we get in the create shipments call response.                                                   |
| parcels           | Array of parcels<br />[Example with 2 parcels](#multi-parcel-ex)                                                                |
| label\_file\_type | Allowed values:`PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PDF_SINGLE_8X11`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII` |

### <a name="multi-parcel-ex" />Multiple parcels payload example

```json theme={null}
"parcels": [
       {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               },
               {
                   "title": "Hippo Magazines -2",
                   "variant_title": "June edition",
                   "sku": "HM-1234",
                   "hs_code": "21234",
                   "quantity": 1,
                   "amount": "15.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       {
           "length": "10",
           "width": "5",
           "height": "8",
           "distance_unit": "cm",
           "weight": 3,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines - 2",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       }
   ]


```

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
   "rate": "74800d3fa6734d88ad65b88dc4ed2008",
   "label_file_type": "PDF",
   "async": false
}'

```

#### Response Sample

```json theme={null}
{
  {
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-14T16:31:14.268Z",
    "object_updated": "2022-12-14T16:31:21.494Z",
    "object_id": "b470b8cae35544728279664d33cd3abb",
    "object_owner": "nataliya_eng@shippo.com",
    "test": true,
    "rate": "562f1c1a920949789702b67c24d514fe",
    "tracking_number": "2908922",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://apgecommerce.com/?page_id=18102908922",
    "label_url": "https://dev-qa-deliver.shippodev.com/b470b8cae35544728279664d33cd3abb.pdf?Expires=1702571481&Signature=X2I6CEAXakpxb3GFiwxa0RwYezqOpMRnRsK55WBYkMrcKB5KttFBZumgjUfLxDmBXjHMDyaX9EBT6iYS4LQXPgu2EGguePYIZzp9vCeSjjzr4fsqR7Qz-g3URrGn~ljI5fa2Cp4kXJ2V9lH7GaPGQkzzRQa7YDBP7JT0Eo3R1gqZt8i3eJin97We-r4hw8DL70rAp5mdPNNZHydg2NQBuHWCLbW6D4a~0GaARlU~dsMqGzKCrfc-MPgCiKYI8FOgLH3yY9mVM7pWILB-MWZ3MOX0EOnnKyHROskBPyS4XbpYGC~kNo2ZihwwZyO2zSHg-AwdTXMEV3XZSOFSYX0lNA__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "commercial_invoice_url": "https://dev-qa-deliver.shippodev.com/ci_b470b8cae35544728279664d33cd3abb.pdf?Expires=1702571481&Signature=E5ECWAA1x3oKrDN-2zuhwrIjlsX3Z3fr7dfFEqpeeSuTAhn9DJXlM3dMm~ecpuoLn5McoEfFtg0ZnSIQLrlqqJvnbqfUNpPgUrZsjnABpK7tJeCqq8CQQB2ttar8HMNuPe7oSJlljrcfAA93-mjuI~1ddT7rTGOvazIizawpSKmppbPjJdzuvMS~s2YHaaIFQXMl1vFK0PDI6TyKAAJKIpEs3FOaqDnTSXZi1Ym0g3JIQEq2~kNJ6oEZ5jLc-fciO7rwh4qJApSbpAbMic6YkHkrbN0YEbY9tSgCwM7sLwJSnndFqY~6-XvveLSfwRmvNXVZ58qB9FZ82~~qS8Pi~g__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "messages": [],
    "order": null,
    "metadata": "",
    "parcel": "bf4356b1eda94d30be17662df1ed6e4e",
    "billing": {
        "payments": []
    },
    "qr_code_url": null
}


}

```

## Purchase label in one call

This is a flow where we create a shipment object from the request payload and return label for it in one call.
This is useful if you already know which carrier and service you want to use.

### Request Payload

| Parameter             | Description                                                                                                                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| shipment\*            | [Refer to the Shipment object](#shipment).                                                                                                                                                      |
| carrier\_account\*    | `object_id` of the carrier account to be used for purchasing this label. This carrier account object\_id is available when an account is created.                                               |
| servicelevel\_token\* | Name of the service level to use. For APG must be one of the following:<br />`epacket`<br /> `epacket_plus`<br />`eparcel_premium`<br />`apg_eparcel_expedited` <br />These are case sensitive. |
| label\_file\_type\*   | Allowed values:<br />`PDF`<br />`PDF_A4`<br />`PDF_A6`<br />`PDF_4x6`<br />`PDF_4x8`<br />`PDF_SINGLE_8X11`<br />`PDF_2.3x7.5`<br />`PNG`<br />`PNG_2.3x7.5`<br />`ZPLII`                       |

### <a name="shipment" /> Shipment

| Parameter       | Description                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| address\_from\* | [Refer to the Address object](/carriers/integration-guides/apg/create-shipment#address)                |
| address\_to\*   | [Refer to the Address object](/carriers/integration-guides/apg/create-shipment#address)                |
| parcels\*       | List of Parcel objects. [Refer Parcel object](/carriers/integration-guides/apg/create-shipment#parcel) |
| extra           | [Refer to the Extra object](/carriers/integration-guides/apg/create-shipment#extra)                    |

### Example

#### Request sample for label creation with single call

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "shipment": {
       "object_purpose": "PURCHASE",
       "address_from": {
           "object_purpose": "PURCHASE",
           "name": "Shipping Mgr",
           "company": "Shippo",
           "street1": "4727 W 1st St",
           "street2": "",
           "city": "New York",
           "state": "NY",
           "zip": "10005",
           "country": "US",
           "phone": "12028642186",
           "email": "nataliya_eng@shippo.com",
           "is_residential": false
       },
       "address_to": {
           "object_purpose": "PURCHASE",
           "name": "Nata Lee",
           "street1": "1720 S Grand Ave",
           "city": "Sydney",
           "state": "VIC",
           "zip": "3026",
           "country": "AU",
           "phone": "+1 666 147 2589",
           "email": "nata@gmail.com",
           "metadata": "",
           "is_residential": true
       },
       "parcels": {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       "customs_declaration": {
           "contents_type": "MERCHANDISE",
           "certify": true,
           "certify_signer": "Test Certifier",
           "incoterm": "DDP",
           "is_vat_collected": "paid",
           "exporter_identification": {
               "tax_id": {
                   "type": "IOSS",
                   "number": "TAXNUMBER12345"
               }
           },
           "items": [
               {
                   "description": "shirt",
                   "quantity": 1,
                   "net_weight": "1",
                   "mass_unit": "oz",
                   "value_amount": "10",
                   "value_currency": "USD",
                   "origin_country": "US",
                   "tariff_number": "",
                   "metadata": "ts mi"
               }
           ]
       },
       "extra": {
           "reference_1": "123456780",
           "carrier_hub_id": "ORD"
       },
       "metadata": "Customer ID 123456",
       "async": false
   },
   "label_file_type": "PDF",
   "carrier_account": "{{APG_ACC}}",
   "servicelevel_token": "eparcel_premium"
}’


```

#### Response sample

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-14T16:28:24.551Z",
    "object_updated": "2022-12-14T16:28:37.611Z",
    "object_id": "b194569f472c4dd9b9175ce498bcb914",
    "object_owner": "nataliya_eng@shippo.com",
    "test": true,
    "rate": {
        "object_id": "562f1c1a920949789702b67c24d514fe",
        "amount": "9.92",
        "currency": "USD",
        "amount_local": "14.45",
        "currency_local": "AUD",
        "provider": "APG",
        "servicelevel_name": "eParcel premium",
        "servicelevel_token": "eparcel_premium",
        "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0"
    },
    "tracking_number": "2908920",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://apgecommerce.com/?page_id=18102908920",
    "label_url": "https://dev-qa-deliver.shippodev.com/b194569f472c4dd9b9175ce498bcb914.pdf?Expires=1702571314&Signature=AevKXrScFoYs8a1olpQIAFM0trtLm5ZFiXa4PQwUvCR38AUBLzoPN87xwafHLflD5LgvhvIVsQ9DZ~qR8-UE~Ke9cVciH3HsaU5GTHUEDGWabjghi8NJim4lARzJH38SrwQtRGlhVse9EIgvDt9GGoptyPtz2ypRuvFUhKnbGnSV2E2Qdvmw5rJqdzHNT4eoIZMWWgrh9fBdismZ0CnplnxzaGpxXygUKzbinii~EAzHLsaEYY-AdiaSFi3TJ7agzQj3aoGVjmtdaup20aJ5BGsYcQacNayW-1SlIrrBbtVeYRC8Jm3SyGIgntsAGfO93Zfnrc~CQAsCyjlR0dS1tw__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "commercial_invoice_url": "https://dev-qa-deliver.shippodev.com/ci_b194569f472c4dd9b9175ce498bcb914.pdf?Expires=1702571317&Signature=iR-md7Vs8i8LxFokLV8TsnvHACaRn-Xj0XxS1djr9IKHYb17LoQEkqlLW7rrj5xXqroRTAxCpRtiFJuu2DclAkMxpdUsise8p4lShODyL0IzU23hyvMWaTnHgPF1rc1PCIsmn-uUvvwJ2je4FhF3rlOj2JsKKnuY0binBsQyyTbwvqhJ1DQ2IleMd85X8Oljj22W5kOop3aVaAw~-laRzAm5Qghot-clCeDvYNDQnbtDKumFE3-K-yGDhudljmlyS3mgnScFz5k0o2Je8bBGTwhmRPTl32O4Tq17QCrbW7v5CwN~bDl6qzrl2efAsns1m74fUfsYeQpausts-ueWpw__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "messages": [],
    "order": null,
    "metadata": "",
    "parcel": "bf4356b1eda94d30be17662df1ed6e4e",
    "billing": {
        "payments": []
    },
    "qr_code_url": null
}

  
```


# Weights and dimensions rules
Source: https://docs.goshippo.com/carriers/integration-guides/apg/weights-and-dimensions-rules

Review APG weight limits and dimension rules by destination country and product type for international shipments.

|   Destination  | Destination IsoCountry |   Product Type   |   Weight limit   |                         Dimensions limit                         |
| :------------: | :--------------------: | :--------------: | :--------------: | :--------------------------------------------------------------: |
|    Australia   |           AU           |      ePacket     |        2KG       |                  Length \<600mm, L+W+H \< 900mm                  |
|    Australia   |           AU           |    ePacketPlus   |        2KG       |                  Length \<600mm, L+W+H \< 900mm                  |
|    Australia   |           AU           |  eParcelPremium  |       22KG       | No one side > 105 cm Length<br /> Dimension \< 0.25 cubic meters |
|    Australia   |           AU           | EParcelExpedited |       20 KG      |     (W+H) \* 2 \< 140 cm<br /> <br /><br /> Length \< 105 cm     |
|   New Zealand  |           NZ           | EParcelExpedited |       20 KG      |     (W+H) \* 2 \< 140 cm<br /> <br /><br /> Length \< 105 cm     |
|    Guernsey    |           GG           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|    Guernsey    |           GG           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|    Guernsey    |           GG           |  eParcelPremium  | From 3KG to 17KG |          L: 90cm<br /> L+W: 150cm<br /> Volume: 0.113m³          |
|    Hong Kong   |           HK           | EParcelExpedited |       30 KG      |                        120cm \*60cm \*60cm                       |
|    Hong Kong   |           HK           |  eParcelPremium  |       30KG       |                        120cm \*60cm \*60cm                       |
|   Isle of Man  |           IM           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|   Isle of Man  |           IM           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|   Isle of Man  |           IM           |  eParcelPremium  | From 3KG to 17KG |          L: 90cm<br /> L+W: 150cm<br /> Volume: 0.113m³          |
|     Israel     |           IL           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|     Israel     |           IL           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|     Israel     |           IL           |  eParcelPremium  |       20KG       |                        100cm \*80cm \*60cm                       |
|     Jersey     |           JE           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|     Jersey     |           JE           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|     Jersey     |           JE           |  eParcelPremium  | From 3KG to 17KG |          L: 90cm<br /> L+W: 150cm<br /> Volume: 0.113m³          |
|   New Zealand  |           NZ           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|   New Zealand  |           NZ           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|   New Zealand  |           NZ           |  eParcelPremium  |       20KG       |                       (W+H) \* 2 \< 140 cm                       |
| United Kingdom |           GB           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
| United Kingdom |           GB           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
| United Kingdom |           GB           |  eParcelPremium  | From 3KG to 17KG |          L: 90cm<br /> L+W: 150cm<br /> Volume: 0.113m³          |
|    Singapore   |           SG           |      ePacket     |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|    Singapore   |           SG           |    ePacketPlus   |        2KG       |                   L\< 60 cm, L + W + H \< 90cm                   |
|    Singapore   |           SG           |  eParcelPremium  |       30KG       |                   L\<1.4, (L + 2W + 2H ) \< 3m                   |


# Get your Carrier Account Details
Source: https://docs.goshippo.com/carriers/integration-guides/better-trucks/create-an-account

Add your Better Trucks carrier account to Shippo using your API key and account ID to start creating shipments.

To use Better Trucks as your preferred carrier, you must [use your own account](#use-your-own-carrier-account) and share your account details with Shippo. This is useful if you have negotiated your own shipping discounts with your preferred carrier. You can still use all the supported Shippo features.

***

## Use your own carrier account

Follow this guide to add your Better Trucks account to Shippo. After adding your account, Shippo can use your account details for generating shipping rates and creating labels.
This step requires you to have your Better Trucks account id and password.

<Info>
  Don't already have a Better Trucks account? Contact our [support team](https://support.goshippo.com/hc/en-us/requests/new?_ga=2.121852172.681514854.1679393926-750891451.1658151685) to help you get signed up.
</Info>

This step should only be completed once. When you have created your carrier account, you can use the carrier `object_id` to reference your carrier.

### HTTP Method

POST

### URL

```
https://api.goshippo.com/carrier_accounts/
```

### Request Payload

| Parameter     | Description                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| carrier\*     | `better_trucks`                                                                                                                                                |
| account\_id\* | A unique identifier for the account which cannot be changed later. Used only for internal purposes                                                             |
| parameters\*  | parameters is an array of additional parameters for the account, such as password or token. Check [Better Trucks parameters](#account_params) for more details |
| active        | Set to `true` to enable account. Set to `false` to disable account.                                                                                            |
| test          | Set to `true` if you want to set the account in test mode. Using test mode you can generate test labels without incurring a charge                             |

Note: Parameters with an \* are mandatory

### <a name="account_params" /> Better Trucks Account Parameters

| Parameter     | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| api\_key\*    | Key to access the API. A string value Better Trucks assigns to each client. |
| account\_id\* | Key to access the API. A string value Better Trucks assigns to each client. |

### Response Code

201

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "carrier": "better_trucks",
   "account_id": "Better_truck_account",
   "parameters": {
       "api_key": "unique_api_key_should_be_here",
       "account_id": "unique_account_id_should_be_here"
   },
   "test": true,
   "active": true
}'

```

#### Response Sample

```json theme={null}
 {
   "carrier": "better_trucks",
   "object_id": "a00414e75df144b596673979108bbab5",
   "object_owner": "nataliya_eng@shippo.com",
   "account_id": "Better_truck_account",
   "parameters": {
       "api_key": "******",
       "account_id": "UNIQUE_ACCOUNT_ID_HERE"
   },
   "test": false,
   "active": true,
   "is_shippo_account": false,
   "metadata": "",
   "carrier_name": "BetterTrucks",
   "carrier_images": {
       "200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/bettertrucks.png",
       "75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/bettertrucks.png"
   }
}



```

Once you have retrieved the `object_id` for your carrier, proceed to [Step 2: Create shipment](/carriers/integration-guides/better-trucks/create-shipment).


# Create shipment
Source: https://docs.goshippo.com/carriers/integration-guides/better-trucks/create-shipment

Create a Better Trucks shipment with addresses, parcel details, and extras like signature confirmation to get rates.

The second step is to create a shipment. The shipment includes all the details about the item you are shipping including

* the "from" and "to" addresses
* the parcel details
* extra parameters

Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/shipments/
```

## Request Payload

| Parameter         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_from\*   | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| address\_to\*     | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| parcels\*         | [Refer to the Parcel object](#parcel)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| extra             | [Refer to the Extra object](#extra)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| carrier\_accounts | An array of object\_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object\_id is available when an account is created.  See [carrier account response](/carriers/integration-guides/better-trucks/create-an-account#response-sample) sample. If no carrier account object\_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the `active` field set to true |
| async             | If set to `false` in the request, this will be populated with all available rates in the response. Otherwise, rates will be created asynchronously and this array will initially be empty                                                                                                                                                                                                                                                                                             |

Note: Parameters with an \* are mandatory

## Objects

### <a name="address" /> Address

| Parameter  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| name\*     | First and Last name of the addressee                                           |
| company\*  | Company Name                                                                   |
| street1\*  | First street line, 35 character limit. Usually street number and street name   |
| street\_no | Street number of the addressed building. This field can be included in street1 |
| street2    | Second street line, 35 character limit                                         |
| city\*     | Name of a city                                                                 |
| zip\*      | Postal code of an address                                                      |
| state\*    | State/Province values are required for shipments from/to the US.               |
| country\*  | ISO 2 country code                                                             |
| phone      | Phone number of the addressee                                                  |
| email      | E-mail address of the contact person, RFC3696/5321-compliant                   |

### <a name="parcel" /> Parcel

| Parameter        | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| length\*         | Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| width\*          | Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted  |
| height\*         | Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| distance\_unit\* | "cm", "in", "ft", "mm", "m", "yd"                                                                        |
| weight\*         | Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| mass\_unit\*     | "g", "oz", "lb", "kg"                                                                                    |

### <a name="extra" /> Extra

| Parameter               | Description                                                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| signature\_confirmation | Sets if signature confirmation is required for this shipment. Possible values `true` or `false` for one of such fields: <br /> - `signature_confirmation` <br /> - `Is_over_21_required` |
| alcohol                 | Need to fill if shipment contains alcohol: <br /> "alcohol":  <br /> "contains\_alcohol": false <br />                                                                                   |

## Response Code

201

## Examples

### Request Sample for a shipment

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "address_from": {
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street1": "4638 Demaret Drive",
       "street2": "Carls Men",
       "city": "Agnew",
       "state": "California",
       "zip": "60612",
       "country": "US",
       "phone": "+15187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "metadata":"Testing purposes"
   },
   "address_to": {
       "name": "John doe",
       "company": "Does Co.",
       "street1": "1009 Independence",
       "street2": "Happy Ford",
       "city": "Capitol Hill",
       "state": "Washington",
       "zip": "30064",
       "country": "US",
       "phone": "+16783034845",
       "email": "rchamberlain@shippo.com",
       "is_residential": true,
       "metadata": "Testing_purposes"
   },
   "parcels": [
       {
           "weight": "49",
           "length": "36",
           "width": "22",
           "height": "22",
           "distance_unit": "in",
           "mass_unit": "lb"
        }
   ],
   "extra": {
       "signature_confirmation": true,
       "alcohol": {
           "contains_alcohol": false
       }
   },
   "carrier_accounts": [
       "{{BETTER_TRUCKS_ACC}}"
   ],
   "async": false
}’



```

### Response Sample for a shipment

```json theme={null}
  {
   "carrier_accounts": [
       "a00414e75df144b596673979108bbab5"
   ],
   "object_created": "2023-01-26T09:51:40.552Z",
   "object_updated": "2023-01-26T09:51:40.552Z",
   "object_id": "bccddc15133b485d8353a647992abc46",
   "object_owner": "nataliya_eng@shippo.com",
   "status": "SUCCESS",
   "address_from": {
       "object_id": "63970df719d24376b52a65dcae9bdf66",
       "is_complete": true,
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street_no": "",
       "street1": "4638 Demaret Drive",
       "validation_results": {},
       "street2": "Carls Men",
       "street3": "",
       "city": "Agnew",
       "state": "CA",
       "zip": "60612",
       "country": "US",
       "phone": "0015187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "test": false
   },
   "address_to": {
       "object_id": "4c9dd8a1d13748b2a7770e8e0d004180",
       "is_complete": true,
       "name": "John doe",
       "company": "Does Co.",
       "street_no": "",
       "street1": "1009 Independence",
       "validation_results": {},
       "street2": "Happy Ford",
       "street3": "",
       "city": "Capitol Hill",
       "state": "WA",
       "zip": "30064",
       "country": "US",
       "phone": "0016783034845",
       "email": "rchamberlain@shippo.com",
       "is_residential": true,
       "test": false
   },
   "parcels": [
       {
           "object_state": "VALID",
           "object_created": "2023-01-26T09:51:40.509Z",
           "object_updated": "2023-01-26T09:51:40.597Z",
           "object_id": "203ce92b5a0944ada594bde482f719ff",
           "object_owner": "nataliya_eng@shippo.com",
           "template": null,
           "extra": {},
           "length": "36.0000",
           "width": "22.0000",
           "height": "22.0000",
           "distance_unit": "in",
           "weight": "49.0000",
           "mass_unit": "lb",
           "value_amount": null,
           "value_currency": null,
           "metadata": "",
           "line_items": [],
           "test": false
       }
   ],
   "shipment_date": "2023-01-26T09:51:40.509Z",
   "address_return": {
       "object_id": "63970df719d24376b52a65dcae9bdf66",
       "is_complete": true,
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street_no": "",
       "street1": "4638 Demaret Drive",
       "validation_results": {},
       "street2": "Carls Men",
       "street3": "",
       "city": "Agnew",
       "state": "CA",
       "zip": "60612",
       "country": "US",
       "phone": "0015187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "test": false
   },
   "alternate_address_to": null,
   "customs_declaration": null,
   "extra": {
       "signature_confirmation": true,
       "alcohol": {
           "contains_alcohol": false
       }
   },
   "rates": [
       {
           "object_created": "2023-01-26T09:51:41.097Z",
           "object_id": "85e1d73986d648bba2b0151e1f90719a",
           "object_owner": "nataliya_eng@shippo.com",
           "shipment": "bccddc15133b485d8353a647992abc46",
           "attributes": [
               "CHEAPEST"
           ],
           "amount": "48.76",
           "currency": "USD",
           "amount_local": "48.76",
           "currency_local": "USD",
           "provider": "Better Trucks",
           "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/bettertrucks.png",
           "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/bettertrucks.png",
           "servicelevel": {
               "name": "Next Day",
               "token": "better_trucks_next_day",
               "terms": "",
               "extended_token": "better_trucks_next_day",
               "parent_servicelevel": null
           },
           "estimated_days": null,
           "arrives_by": "13:00:00",
           "duration_terms": "",
           "messages": [],
           "carrier_account": "a00414e75df144b596673979108bbab5",
           "test": false,
           "zone": null
       }
   ],
   "messages": [],
   "metadata": "",
   "test": false,
   "order": null
}
```


# Purchase label
Source: https://docs.goshippo.com/carriers/integration-guides/better-trucks/purchase-label

Purchase a Better Trucks shipping label from an existing shipment rate or create one in a single API call.

The final step is to purchase the shipment. This will generate your shipping label.

There are two ways to purchase a shipment.

1. You can [purchase the shipment object](#purchase-from-created-shipment) you created in the last step
2. You can purchase a label without a [shipment object in a single call](#purchase-label-in-one-call)

## HTTP Method

POST

## URL

```
https://api.goshippo.com/transactions/
```

## Purchase from created Shipment

This is a flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided `rate`.

### Request Payload

| Parameter           | Description                                                                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| rate\*              | `object_id` of the rate object we get in the [create shipments call response](/carriers/integration-guides/better-trucks/create-shipment#request-sample-for-a-shipment). |
| label\_file\_type\* | Allowed values: `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PDF_SINGLE_8X11`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII`                                         |
|                     |                                                                                                                                                                          |

Note: Parameters with an \* are mandatory

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
   "rate": "4af61f01e2a44ecbb6c278a1d573f1ff",
   "async": false,
   "label_file_type": "PDF"
}’


```

#### Response Sample

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2023-02-01T09:38:24.238Z",
   "object_updated": "2023-02-01T09:38:27.042Z",
   "object_id": "48ee2ce651894bf3bb37f1af0612bd6a",
   "object_owner": "expn-prod-test@shippo.com",
   "test": true,
   "rate": "4af61f01e2a44ecbb6c278a1d573f1ff",
   "tracking_number": "BTS_001807L4NVV",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "https://tracking.bettertrucks.com/Tracking?ShipmentId=jhfBTS_001807L4NVV",
   "label_url": "https://dev-qa-deliver.shippodev.com/48ee2ce651894bf3bb37f1af0612bd6a.pdf?Expires=1706780306&Signature=OFKPm1PuMuFJKVEnVXAkfw-gJ2SsJmUN1VzeZ66VCUj5r~rmOp5ze~XvEhQTGKR8YjWTjv0dVg3Mo1h9sgQBQmVdPZ0tXIgr1g1NVcGrSYf6duqvv~IczKvdtA2aI2lkMvT-Q4Kb1KvdW37dnJTzCGB2jJBNnz-N44n2j4JEpuNc-Iq6jJlJXPAJHKJPLVAxoI77klfthSSzRN0reCfItSCybDs1a~F2PQ1rKl-wf~60en419OI4JR0C0E-aUjaz~EvBh8e2gBvAU-rmxsB13yJiAI3WtTayCIlATAJ5svdiLvZiKAn6oWkOtwQ6rnX3OcOPVJh1mCUCymvTxdGAgg__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "ea911c30d3904d9881ebbe698c6d0cca",
   "billing": {
       "payments": []
   },
   "qr_code_url": null
}

```

This is an example of the label that is created.

<img alt="Sample label created using a Shipment object" />

## Purchase label in one call

This is a flow where we create a shipment object from the request payload and return label for it in one call

### Request Payload

| Parameter             | Description                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| shipment\*            | [Refer to the Shipment object](#shipment).                                                                                                        |
| carrier\_account\*    | `object_id` of the carrier account to be used for purchasing this label. This carrier account object\_id is available when an account is created. |
| servicelevel\_token\* | Name of the service level to use. For now, only `better_trucks_next_day` is supported. This are case sensitive.                                   |
| label\_file\_type\*   | Allowed values: `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PDF_SINGLE_8X11`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, ZPLII                    |

### <a name="shipment" /> Shipment

| Parameter       | Description                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| address\_from\* | [Refer to the Address object](/carriers/integration-guides/better-trucks/create-shipment#address)                |
| address\_to\*   | [Refer to the Address object](/carriers/integration-guides/better-trucks/create-shipment#address)                |
| parcels\*       | List of Parcel objects. [Refer Parcel object](/carriers/integration-guides/better-trucks/create-shipment#parcel) |
| extra           | [Refer to the Extra object](/carriers/integration-guides/better-trucks/create-shipment#extra)                    |

### Examples

#### Request sample for a shipment in one call

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
{
   "shipment": {
       "address_from": {
           "name": "Mr. Hippo",
           "company": "Shippo & Son",
           "street1": "1901 W Madison Street",
           "street2": "Press Box 23",
           "city": "Chicago",
           "state": "IL",
           "zip": "60612",
           "country": "US",
           "phone": "+1 555 341 9393",
           "email": "support@shippo.com"
       },
       "address_to": {
           "name": "Mrs. Hippo",
           "company": "Shippo & Co",
           "street1": "100 STOCKYARD",
           "city": "Nashville",
           "state": "TN",
           "zip": "37201",
           "country": "US",
           "metadata": "Customer ID 123456"
       },
       "parcels": [
           {
               "weight": "8",
               "length": "9",
               "width": "9",
               "height": "8",
                "distance_unit": "in",
               "mass_unit": "lb"
           }
       ],
       "extra": {
           "signature_confirmation": true,
           "alcohol": {
               "contains_alcohol": false
           }
       }
   },
   "carrier_account": "{{BETTER_TRUCKS_ACC}}",
   "async": false,
   "servicelevel_token": "better_trucks_next_day",
   "label_file_type": "PDF_4x6"
 }'



```

#### Response sample for a shipment in one call

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2023-01-26T09:52:08.935Z",
   "object_updated": "2023-01-26T09:52:11.715Z",
   "object_id": "09ae917f995e494fa3644d2681c4dbc7",
   "object_owner": "nataliya_eng@shippo.com",
   "test": false,
   "rate": {
       "object_id": "7df6b9381e424b21a682c49aea8c9614",
       "amount": "6.02",
       "currency": "USD",
       "amount_local": "6.02",
       "currency_local": "USD",
       "provider": "Better Trucks",
       "servicelevel_name": "Next Day",
       "servicelevel_token": "better_trucks_next_day",
       "carrier_account": "a00414e75df144b596673979108bbab5"
   },
    "tracking_number": "BTS_0018FQYZ3H5",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "https://tracking.bettertrucks.com/Tracking?ShipmentId=jhfBTS_0018FQYZ3H5",
   "label_url": "https://dev-qa-deliver.shippodev.com/09ae917f995e494fa3644d2681c4dbc7.pdf?Expires=1706262731&Signature=CtTyLLrL4PB4DD-o7-BTZ9jUB8p2XSCDHmWnZaMoVLFqfSwAsXCfy4MLNRqMceaRfz2uftvWeL5MgsL1TTElKUpuaawgBqaK6nFWj3cxVoWb94skkfiqzqPjqyIL9rsuKg6HxmKEjmQIDfGYjK3r3M2dTBfiauDTB4lueFmKSS41yLdV0JMeJT8y-SY13iBcKTelUMEHNwMiDGQV2D8Cag6nJoTAb-b7Ktw3ogO1xMprqCduv8MuwtvYiYPZfkHzmHdaGZ7YXGNGpH5IkeRvgUFYufzLXRfcYX0e-9d7joRTXmaIOcIRiNrZLdR9TVugg8b87LkciWMjJssCJ7ZW7g__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "e03be392226849a3a4ee380a9aced3e2",
   "billing": {
       "payments": []
   },
   "qr_code_url": null
}
```

This is an example of the label that is created.

<img alt="Example label created form a single call purchase" />

## Response

A successful response includes all the details about your purchased shipment including tracking details and a link to your shipping label.


# Track
Source: https://docs.goshippo.com/carriers/integration-guides/better-trucks/track

Track your Better Trucks shipments using the Shippo Tracking API with the tracking number from your label purchase.

If you purchased your shipping label through Shippo, you can also get all the tracking details of your Shipment using the Tracking API.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/tracks/better_trucks/track_number_id/
```

### Request Payload

| Parameter in URL    | Description                                                                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| track\_number\_id\* | `tracking_number` value of the transaction response, we get in the transaction call response. [create shipments call response](/carriers/integration-guides/better-trucks/create-shipment#request-sample-for-a-shipment). |

## Response Code

200 OK

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request GET 'https://api.goshippo.com/tracks/better_trucks/BTS_0018P2LD557/’\
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
}’

```

#### Response Sample

```json theme={null}
{
   "tracking_number": "BTS_0018P2LD557",
   "carrier": "better_trucks",
   "servicelevel": {
       "name": null,
       "token": null
   },
   "transaction": "6ceb8e3fc07446d08c5c5884ccb4b1b4",
   "address_from": {
       "city": "Chicago",
       "state": "IL",
       "zip": "60612",
       "country": "US"
   },
   "address_to": {
      "city": "Nashville",
       "state": "TN",
       "zip": "37201",
       "country": "US"
   },
   "eta": null,
   "original_eta": null,
   "metadata": null,
   "test": false,
   "tracking_status": null,
   "tracking_history": [
       {
           "status_date": null,
           "status_details": "Pre-Transit: Shipment information has been transmitted to the shipping carrier but it has not yet been scanned and picked up.",
           "location": null,
           "substatus": null,
           "object_created": "2023-01-26T18:37:13.668Z",
           "object_updated": "2023-01-26T18:37:13.668Z",
           "object_id": "24d41f49a9ac419e8d66f7fae4fce705",
           "status": "UNKNOWN"
       }
   ],
   "messages": []
}




```


# Get your Carrier Account Details
Source: https://docs.goshippo.com/carriers/integration-guides/colissimo/create-an-account

Use Shippo's built-in Colissimo account or connect your own Colissimo carrier account to start creating shipments.

There are two ways to use a carrier account with Shippo.

The first is to [use Shippo's account](#use-the-shippo-carrier-account) with your preferred carrier to create shipping labels.
Using Shippo's account makes it easier to get started and means you benefit from the shipping discounts that Shippo has negotiated with the carrier.

The second way is to [use your own account](#use-your-own-carrier-account) with your preferred carrier and share your account details with Shippo. This is useful if you have negotiated your own shipping discounts with your preferred carrier. You can still use all the supported Shippo features.

## Use the Shippo carrier account

To use the Shippo, Colissimo account, you must retrieve the carrier account `object_id`.
This step should only be completed once. In future transactions, you can use the carrier `object_id` to reference your carrier.

### HTTP Method

GET

### URL

```
https://api.goshippo.com/carrier_accounts/
```

### Example

#### Request Sample

```shell cURL theme={null}
  curl --location --request GET 'https://api.goshippo.com/carrier_accounts?carrier=colissimo' \
  --header 'Authorization: ShippoToken <API_TOKEN>' \
  --header 'Content-Type: application/json'
```

#### Response Sample

```json theme={null}
{
  "carrier": "colissimo",
  "object_id": "4a4dfb5425ea41b6be2e851306284bf5",
  "object_owner": "test-user@shippo.com",
  "account_id": "shippo_colissimo_account",
  "parameters": {},
  "test": false,
  "active": true,
  "is_shippo_account": true,
  "metadata": "",
  "carrier_name": "Colissimo",
  "carrier_images": {
    "75": "https://shippo-static.s3.amazonaws.com/providers/75/colissimo.png",
    "200": "https://shippo-static.s3.amazonaws.com/providers/200/colissimo.png"
  }
}
```

Note: If you did not receive a response like this, the carrier may not have been enabled for your account. Contact [Shippo support](https://support.goshippo.com/hc/en-us/requests/new?_ga=2.259093706.1751315872.1670840488-750891451.1658151685) for more infomation.

Once you have retrieved the `object_id` for your carrier, proceed to [Step 2: Create shipment](/carriers/integration-guides/colissimo/create-shipment).

***

## Use your own carrier account

If you want to use your own Colissimo account, follow this guide to add your Colissimo account to Shippo. After adding your account, Shippo can use your account details for generating shipping rates and creating labels.
This step requires you to have your Colissimo account id and password.

This step should only be completed once. When you have created your carrier account, you can use the carrier `object_id` to reference your carrier.

### HTTP Method

POST

### URL

```
https://api.goshippo.com/carrier_accounts/
```

### Request Payload

| Parameter     | Description                                                                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| carrier\*     | `colissimo`                                                                                                                                                |
| account\_id\* | A unique identifier for the account which cannot be changed later. This should be a username provided by Colissimo                                         |
| parameters\*  | parameters is an array of additional parameters for the account, such as password or token. Check [Colissimo parameters](#account_params) for more details |
| active        | Set to `true` to enable account. Set to `false` to disable account.                                                                                        |
| test          | Set to `true` if you want to set the account in test mode. Using test mode you can generate test labels without incurring a charge                         |

Note: Parameters with an \* are mandatory

### <a name="account_params" /> Colissimo Account Parameters

| Parameter  | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| password\* | Password to access the API. Password and account\_id are tied together and should be provided by Colissimo |

### Response Code

201

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "carrier": "colissimo",
   "account_id": "collisimo_account",
   "parameters": {
       "password": "EXAMPLE_PASSWORD",
   },
   "active": true,
   "test": true
}'

```

#### Response Sample

```json theme={null}
{
    "carrier": "colissimo",
    "object_id": "4a4dfb5425ea41b6be2e851306284bf5",
    "object_owner": "test-user@shippo.com",
    "account_id": "******",
    "parameters": {
        "password": "******"
    },
    "test": true,
    "active": true,
    "is_shippo_account": false,
    "metadata": "",
    "carrier_name": "Colissimo",
    "carrier_images": {
        "200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
        "75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png"
    }
}

```

Once you have retrieved the `object_id` for your carrier, proceed to [Step 2: Create shipment](/carriers/integration-guides/colissimo/create-shipment).


# Create shipment
Source: https://docs.goshippo.com/carriers/integration-guides/colissimo/create-shipment

Create a Colissimo shipment with addresses, parcels, and customs declarations for domestic or international shipping.

The second step is to create a shipment. The shipment includes all the details about the item you are shipping including

* the "from" and "to" addresses
* the parcel details
* extra parameters
* customs declaration, that are required for [international shipments](#request-sample-for-an-international-shipment)

Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/shipments/
```

## Request Payload

| Parameter              | Description                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_from\*        | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                         |
| address\_to\*          | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                         |
| parcels\*              | [Refer to the Parcel object](#parcel)                                                                                                                                                                                                                                                                                                                           |
| extra                  | [Refer to the Extra object](#extra)                                                                                                                                                                                                                                                                                                                             |
| customs\_declaration\* | [Refer to the Customs declaration object](#customs_declaration). Required for international shipments                                                                                                                                                                                                                                                           |
| carrier\_accounts      | An array of object\_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object\_id is available when an account is created. If no carrier account object\_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the `active` field set to true |
| async                  | If set to false in the request, this will be populated with all available rates in the response. Otherwise, rates will be created asynchronously and this array will initially be empty                                                                                                                                                                         |

Note: Parameters with an \* are mandatory

## Objects

### <a name="address" /> Address

| Parameter  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| name\*     | First and Last name of the addressee                                           |
| company\*  | Company Name                                                                   |
| street1\*  | First street line, 35 character limit. Usually street number and street name   |
| street\_no | Street number of the addressed building. This field can be included in street1 |
| street2    | Second street line, 35 character limit                                         |
| city\*     | Name of a city                                                                 |
| zip\*      | Postal code of an address                                                      |
| state\*    | State/Province values are required for shipments from/to the US.               |
| country\*  | ISO 2 country code                                                             |
| phone      | Phone number of the addressee                                                  |
| email      | E-mail address of the contact person, RFC3696/5321-compliant                   |

### <a name="parcel" /> Parcel

| Parameter        | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| length\*         | Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| width\*          | Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted  |
| height\*         | Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| distance\_unit\* | "cm", "in", "ft", "mm", "m", "yd"                                                                        |
| weight\*         | Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| mass\_unit\*     | "g", "oz", "lb", "kg"                                                                                    |

### <a name="extra" /> Extra

| Parameter               | Description                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| location\_external\_id  | Should be set when a Pickup point ID is required. For example for `colissimo_pick_up_point` service level                   |
| signature\_confirmation | Sets if signature confirmation is required for this shipment. Will be used to determine the correct service level. Optional |
| reference\_1            | Optional text to be printed on the shipping label. Up to 50 characters                                                      |

### <a name="customs_declaration" />  Customs Declaration

| Parameter             | Description                                                                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| certify\*             | Boolean. Expresses that the certify\_signer has provided all information of this customs declaration truthfully                                                                    |
| certify\_signer\*     | Name of the person who created the customs declaration and is responsible for the validity of all information provided                                                             |
| items\*               | [Refer Items object](#items)                                                                                                                                                       |
| invoiced\_charges     | [Refer Invoiced charges object](#invoiced_charges). An object holding optional invoiced charges data to be printed on the Commercial Invoice. Mandatory for international shipping |
| incoterm              | The incoterm reference of the shipment. For International Overseas shipment we can not use DDP. For International Shipment DDP, DDU, DAP, Empty can be used                        |
| contents\_type\*      | Type of goods of the shipment                                                                                                                                                      |
| contents\_explanation | This field is mandatory for contents\_type = OTHER                                                                                                                                 |
| hs\_code              | The HS (Harmonised System) or product code is used by customs officers worldwide to categorise products                                                                            |
| invoice               | Invoice reference of the shipment                                                                                                                                                  |

### <a name="items" />  Items

| Parameter         | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| description       | Text description of your item.                                         |
| quantity\*        | Quantity of this item in the shipment you send. Must be greater than 0 |
| net\_weight\*     | Total weight of this item, i.e. quantity \* weight per item            |
| mass\_unit\*      | The unit used for net\_weight                                          |
| value\_amount\*   | Total value of this item, i.e. quantity \* value per item              |
| value\_currency\* | Currency in which value is specified                                   |
| origin\_country\* | ISO 2 country code                                                     |

### <a name="invoiced_charges" />  Invoiced charges

| Parameter         | Description                                                                                                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| currency\*        | Currency for the invoiced charges amounts incurred on the end consumer. Needs to be in euros. Check shipment/customs\_declarations/invoiced\_charges/currency, if the currency is other than euros then convert to EUR |
| total\_shipping\* | Total shipping paid by the buyer                                                                                                                                                                                       |

## Response Code

201

## Examples

### Request Sample for a Domestic shipment

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street1": "3 Place du Berry",
        "street2": "Rue Jacques Coeur 756",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "+1888-999-1500",
        "email": "Picardie@shippo.com"
  },
  "address_to": {
      "name": "Chapelaine Carnot",
      "company": "Louis Ulbach",
      "street1": "8 Rue de La Vicomté",
      "street2": "Rue de la Pierre",
      "city": "Aube",
      "state": "Troyes",
      "zip": "10000",
      "country": "FR",
      "phone": "+18889575900",
      "email": "Chapelaine@shippo.com"
  },
  "parcels": [{
    "weight": "1",
    "length": "5",
    "width": "4",
    "height": "1",
    "distance_unit": "cm",
    "mass_unit": "kg"
  }],
    "extra": {
       "reference_1": "Ship.Label_Chrono_Ok"

    },
  "carrier_accounts": ["4a4dfb5425ea41b6be2e851306284bf5"],
  "async": false
}'

```

### Response Sample for a Domestic shipment

```json theme={null}
{
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "object_created": "2022-11-30T12:54:06.091Z",
    "object_updated": "2022-11-30T12:54:06.547Z",
    "object_id": "f500a2e404ac42d5bdf00a92283a8e00",
    "object_owner": "test@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "8024d39aeca24c21a095a2c057ded999",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "691f13e12e584d5eaa5b56c870237f3a",
        "is_complete": true,
        "name": "Chapelaine Carnot",
        "company": "Louis Ulbach",
        "street_no": "",
        "street1": "8 Rue de La Vicomté",
        "validation_results": {},
        "street2": "Rue de la Pierre",
        "street3": "",
        "city": "Aube",
        "state": "Troyes",
        "zip": "10000",
        "country": "FR",
        "phone": "0018889575900",
        "email": "Chapelaine@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-11-30T12:54:06.062Z",
            "object_updated": "2022-11-30T12:54:06.127Z",
            "object_id": "574491335b634d89b3edaca0b55cf420",
            "object_owner": "test@shippo.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "4.0000",
            "height": "1.0000",
            "distance_unit": "cm",
            "weight": "1.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2022-11-30T12:54:06.177Z",
    "address_return": {
        "object_id": "8024d39aeca24c21a095a2c057ded999",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": null,
    "extra": {
        "reference_1": "Ship.Label_Chrono_Ok"
    },
    "rates": [
        {
            "object_created": "2022-11-30T12:54:06.518Z",
            "object_id": "0bd2f0a39733436da688ce2158dd3ad6",
            "object_owner": "test@shippo.com",
            "shipment": "f500a2e404ac42d5bdf00a92283a8e00",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "6.74",
            "currency": "EUR",
            "amount_local": "6.74",
            "currency_local": "EUR",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Point Retrait",
                "token": "colissimo_pick_up_point",
                "terms": "",
                "extended_token": "colissimo_pick_up_point",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "1"
        },
        {
            "object_created": "2022-11-30T12:54:06.518Z",
            "object_id": "8f9ad8dd7bf14991ac2a229254256246",
            "object_owner": "test@shippo.com",
            "shipment": "f500a2e404ac42d5bdf00a92283a8e00",
            "attributes": [],
            "amount": "8.14",
            "currency": "EUR",
            "amount_local": "8.14",
            "currency_local": "EUR",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Domicile",
                "token": "colissimo_home",
                "terms": "",
                "extended_token": "colissimo_home",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "1"
        }
    ],
    "messages": [],
    "metadata": "",
    "test": true,
    "order": null
}

```

### Request sample for an international shipment

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "address_from": {
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street1": "3 Place du Berry",
        "street2": "Rue Jacques Coeur 756",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "+1888-999-1500",
        "email": "Picardie@shippo.com"
    },
    "address_to": {
        "name": "Mr. Hippo",
        "street1": "24 Endell",
        "city": "London",
        "state": "",
        "zip": "W1D 4HS",
        "country": "GB",
        "phone": "01159 663055",
        "email": "mrhippo@shippo.com"
    },
    "parcels": [
        {
            "weight": "1",
            "length": "5",
            "width": "4",
            "height": "1",
            "distance_unit": "cm",
            "mass_unit": "kg"
        }
    ],
    "customs_declaration": {
        "invoiced_charges": {
            "total_shipping": "10.00",
            "currency": "EUR"
        },
        "contents_type": "MERCHANDISE",
        "contents_explanation": "T-Shirt purchase",
        "invoice": "#123123",
        "notes": "Notes here",
        "certify": true,
        "certify_signer": "Test User",
        "incoterm": "DDU",
        "items": [
            {
                "description": "shirt",
                "quantity": 1,
                "net_weight": "7",
                "mass_unit": "oz",
                "hs_code": "AB123C",
                "sku_code": "A333BFEQA",
                "value_amount": "10",
                "value_currency": "EUR",
                "origin_country": "FR"
            }
        ]
    },
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "async": false
}'

```

### Response sample for international shipment

```json theme={null}
{
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "object_created": "2022-12-01T11:09:50.513Z",
    "object_updated": "2022-12-01T11:09:51.028Z",
    "object_id": "c9b3601e6ede46ca8732ee1dd16b9b3e",
    "object_owner": "test@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "30a89b461cad4a2f91d6187d94aba5a8",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "f2a9d19e9cde4bbc89dce5a769fcab45",
        "is_complete": true,
        "name": "Mr. Hippo",
        "company": "",
        "street_no": "",
        "street1": "24 Endell",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "W1D 4HS",
        "country": "GB",
        "phone": "01159663055",
        "email": "mrhippo@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-12-01T11:09:50.291Z",
            "object_updated": "2022-12-01T11:09:50.575Z",
            "object_id": "037869846bab4e2987ca054d4f31b97e",
            "object_owner": "test@shippo.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "4.0000",
            "height": "1.0000",
            "distance_unit": "cm",
            "weight": "1.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2022-12-01T11:09:50.656Z",
    "address_return": {
        "object_id": "30a89b461cad4a2f91d6187d94aba5a8",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": {
        "object_created": "2022-12-01T11:09:50.410Z",
        "object_updated": "2022-12-01T11:09:50.410Z",
        "object_id": "aa43df470809469688a13ab37e624074",
        "object_owner": "test@shippo.com",
        "object_state": "VALID",
        "address_importer": null,
        "certify_signer": "Test User",
        "certify": true,
        "items": [
            "7e39fad7c4e64285ba4224a6962a0bb4"
        ],
        "non_delivery_option": "RETURN",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "T-Shirt purchase",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "#123123",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "notes": "Notes here",
        "eel_pfc": "",
        "aes_itn": "",
        "disclaimer": "",
        "incoterm": "DDU",
        "metadata": "",
        "test": true,
        "duties_payor": null,
        "b13a_filing_option": "",
        "b13a_number": "",
        "invoiced_charges": {
            "total_shipping": "10.00",
            "total_taxes": null,
            "total_duties": null,
            "other_fees": null,
            "currency": "EUR"
        },
        "exporter_identification": null,
        "is_vat_collected": null
    },
    "extra": {},
    "rates": [
        {
            "object_created": "2022-12-01T11:09:50.997Z",
            "object_id": "18db7a1211ee4b2d97e1bad0cbb5ca2f",
            "object_owner": "test@shippo.com",
            "shipment": "c9b3601e6ede46ca8732ee1dd16b9b3e",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "13.10",
            "currency": "EUR",
            "amount_local": "11.26",
            "currency_local": "GBP",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Domicile",
                "token": "colissimo_home",
                "terms": "",
                "extended_token": "colissimo_home",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "international_2_gb"
        }
    ],
    "messages": [],
    "metadata": "",
    "test": true,
    "order": null
}
```


# Purchase label
Source: https://docs.goshippo.com/carriers/integration-guides/colissimo/purchase-label

Purchase a Colissimo shipping label from an existing shipment or create one in a single API call through Shippo.

The final step is to purchase the shipment. This will generate your shipping label.

There are two ways to purchase a shipment.

1. You can [purchase the shipment object](#purchase-from-created-shipment) you created in the last step
2. You can purchase a label without a [shipment object in a single call](#purchase-label-in-one-call)

## HTTP Method

POST

## URL

```
https://api.goshippo.com/transactions/
```

## Purchase from created Shipment

This is a flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided `rate`.

### Request Payload

| Parameter           | Description                                                                                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rate\*              | `object_id` of the rate object we get in the [create shipments call response](/carriers/integration-guides/colissimo/create-shipment#request-sample-for-a-domestic-shipment). |
| label\_file\_type\* | Allowed values: `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PNG`, `ZPLII`                                                                                               |
| async               | Set to true if you want to poll for the result and receive faster response                                                                                                    |

Note: Parameters with an \* are mandatory

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
    "rate": "975445f117db48e5b3e85cebebe87ee0",
    "async": false,
    "label_file_type": "PDF_A4"
}'

```

#### Response Sample

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-10T23:47:18.278Z",
   "object_updated": "2022-11-10T23:47:20.948Z",
   "object_id": "cbc1a12243db44b9ae56ef3ca502b8c3",
   "object_owner": "test-use@shippo.com",
   "test": false,
   "rate": "975445f117db48e5b3e85cebebe87ee0",
   "tracking_number": "00024000110003001",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "e54ef8c0a27c451690bca6f3b6491264",
   "billing": {
       "payments": []
   },
   "qr_code_url": null
}

```

## Purchase label in one call

This is a flow where we create a shipment object from the request payload and return label for it in one call

### Request Payload

| Parameter             | Description                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| shipment\*            | [Refer to the Shipment object](#shipment).                                                                                                                                 |
| carrier\_account\*    | `object_id` of the carrier account to be used for purchasing this label. This carrier account object\_id is available when an account is created.                          |
| servicelevel\_token\* | Name of the service level to use. Must be one of the following: `colissimo_home`, `colissimo_pick_up_point`, `colissimo_return_mainland_france`. These are case-sensitive. |
| label\_file\_type\*   | Allowed values: `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PNG`, `ZPLII`                                                                                            |

### <a name="shipment" /> Shipment

| Parameter              | Description                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_from\*        | [Refer to the Address object](/carriers/integration-guides/colissimo/create-shipment#address)                                                               |
| address\_to\*          | [Refer to the Address object](/carriers/integration-guides/colissimo/create-shipment#address)                                                               |
| parcels\*              | List of Parcel objects. [Refer Parcel object](/carriers/integration-guides/colissimo/create-shipment#parcel)                                                |
| extra                  | [Refer to the Extra object](/carriers/integration-guides/colissimo/create-shipment#extra)                                                                   |
| customs\_declaration\* | [Refer to the Customs declaration object](/carriers/integration-guides/colissimo/create-shipment#customs_declaration). Required for international shipments |

### Examples

#### Request sample for a domestic shipment

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment": {
        "address_from": {
                "name": "Èmile Zola",
                "company": "Palais Jacques Coeur",
                "street1": "3 Place du Berry",
                "street2": "Rue Jacques Coeur 756",
                "city": "Cher",
                "state": "Bourges",
                "zip": "18000",
                "country": "FR",
                "phone": "+1888-999-1500",
                "email": "Picardie@shippo.com"
        },
        "address_to": {
            "name": "Chapelaine Carnot",
            "company": "Louis Ulbach",
            "street1": "8 Rue de La Vicomté",
            "street2": "Rue de la Pierre",
            "city": "Aube",
            "state": "Troyes",
            "zip": "10000",
            "country": "FR",
            "phone": "+18889575900",
            "email": "Chapelaine@shippo.com"
        },
        "parcels": [{
            "weight": "1",
            "length": "5",
            "width": "4",
            "height": "1",
            "distance_unit": "cm",
            "mass_unit": "kg"
        }],
        "extra": {
                "reference_1": "Ship.Label_Chrono_Ok"
        }
    },
  "label_file_type": "PNG",
  "servicelevel_token": "colissimo_home",
  "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
}'

```

#### Response sample for a domestic shipment

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-11T00:19:44.077Z",
   "object_updated": "2022-11-11T00:19:46.446Z",
   "object_id": "c42aabb1755d462395e83150ad74f84b",
   "object_owner": "test-user@shippo.com",
   "test": false,
    "rate": {
        "object_id": "e9ef8e278a4949d697cc48fead716033",
        "amount": "8.14",
        "currency": "EUR",
        "amount_local": "8.14",
        "currency_local": "EUR",
        "provider": "Colissimo",
        "servicelevel_name": "Domicile",
        "servicelevel_token": "colissimo_home",
        "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
    },
   "tracking_number": "AT00024000110003000",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "56sdfhjlbde8d41dd805de409e7b8a729",
   "billing": { 
       "payments": []
   },
   "qr_code_url": null
}
```

#### Request sample for an international shipment

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment": {
        "address_from": {
            "name": "Èmile Zola",
            "company": "Palais Jacques Coeur",
            "street1": "3 Place du Berry",
            "street2": "Rue Jacques Coeur 756",
            "city": "Cher",
            "state": "Bourges",
            "zip": "18000",
            "country": "FR",
            "phone": "+1888-999-1500",
            "email": "Picardie@shippo.com"
        },
        "address_to": {
            "name": "Mr. Hippo",
            "street1": "24 Endell",
            "city": "London",
            "state": "",
            "zip": "W1D 4HS",
            "country": "GB",
            "phone": "01159 663055",
            "email": "mrhippo@shippo.com"
        },
        "parcels": [
            {
                "weight": "1",
                "length": "5",
                "width": "4",
                "height": "1",
                "distance_unit": "cm",
                "mass_unit": "kg"
            }
        ],
        "customs_declaration": {
            "invoiced_charges": {
                "total_shipping": "10.00",
                "currency": "EUR"
            },
            "contents_type": "MERCHANDISE",
            "contents_explanation": "T-Shirt purchase",
            "invoice": "#123123",
            "notes": "Notes here",
            "certify": true,
            "certify_signer": "Test User",
            "incoterm": "DDU",
            "items": [
                {
                    "description": "shirt",
                    "quantity": 1,
                    "net_weight": "7",
                    "mass_unit": "oz",
                    "hs_code": "61091000",
                    "sku_code": "A333BFEQA",
                    "value_amount": "10",
                    "value_currency": "EUR",
                    "origin_country": "FR"
                }
            ]
        },
        "extra": {
            "reference_1": "Ship.Label_Chrono_Ok"
        }
    },
    "label_file_type": "PNG",
    "servicelevel_token": "colissimo_home",
    "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
}'

```

#### Response sample for an international shipment

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-11T00:19:44.077Z",
   "object_updated": "2022-11-11T00:19:46.446Z",
   "object_id": "c42aabb1755d462395e83150ad74f84b",
   "object_owner": "test-user@shippo.com",
   "test": false,
    "rate": {
        "object_id": "e9ef8e278a4949d697cc48fead716033",
        "amount": "8.14",
        "currency": "EUR",
        "amount_local": "8.14",
        "currency_local": "EUR",
        "provider": "Colissimo",
        "servicelevel_name": "Domicile",
        "servicelevel_token": "colissimo_home",
        "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
    },
   "tracking_number": "AT00024000110003000",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "56sdfhjlbde8d41dd805de409e7b8a729",
   "billing": { 
       "payments": []
   },
   "qr_code_url": null
}
```

## Response

A successful response includes all the details about your purchased shipment including tracking details and a link to your shipping label.


# Create shipment
Source: https://docs.goshippo.com/carriers/integration-guides/royal-mail-tracked/create-shipment

Create a Royal Mail Tracked shipment with addresses, parcel details, and customs declarations for UK and international shipping.

The second step is to create a shipment. The shipment includes all the details about the item you are shipping including

* the "from" and "to" addresses
* the parcel details
* extra parameters
* customs declaration, that are required for international shipments (see [Request Example](#request-example) below)

Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/shipments/
```

## Request Payload

| Parameter         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_from\*   | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                                                                |
| address\_to\*     | [Refer to the Address object](#address)                                                                                                                                                                                                                                                                                                                                                                                                                                |
| parcels\*         | [Refer to the Parcel object](#parcel)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| extra             | [Shipments Extras](/api-reference/shipments/list-all-shipments)                                                                                                                                                                                                                                                                                                                                                                                                        |
| carrier\_accounts | An array of object\_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object\_id is available when an account is created. See [carrier account response sample](/carriers/carrier-accounts#connecting-your-own-carrier-account). If no carrier account object\_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the `active` field set to true |
| async             | If set to false in the request, this will be populated with all available rates in the response. Otherwise, rates will be created asynchronously and this array will initially be empty                                                                                                                                                                                                                                                                                |

Note: Parameters with an \* are mandatory

## Objects

### <a name="address" /> Address

| Parameter  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| name\*     | First and Last name of the addressee                                           |
| company\*  | Company Name                                                                   |
| street1\*  | First street line, 35 character limit. Usually street number and street name   |
| street\_no | Street number of the addressed building. This field can be included in street1 |
| street2    | Second street line, 35 character limit                                         |
| city\*     | Name of a city                                                                 |
| zip\*      | Postal code of an address                                                      |
| state\*    | State/Province values are required for shipments from/to the US.               |
| country\*  | ISO 2 country code                                                             |
| phone      | Phone number of the addressee                                                  |
| email      | E-mail address of the contact person, RFC3696/5321-compliant                   |

### <a name="parcel" /> Parcel

| Parameter        | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| length\*         | Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| width\*          | Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted  |
| height\*         | Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| distance\_unit\* | "cm", "in", "ft", "mm", "m", "yd"                                                                        |
| weight\*         | Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted |
| mass\_unit\*     | "g", "oz", "lb", "kg"                                                                                    |

## Response Code

201

## Examples

### Request Example

<Info>
  **Note**

  (Shipments to Northern Ireland require Customs Declaration & Items object)
</Info>

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "async": false,
    "object_purpose": "PURCHASE",
    "carrier_accounts": ["aa79df9091b44e03a5de1538585fdd88"],
    "address_from": {
        "object_purpose": "PURCHASE",
        "name": "London Sender",
        "street1": "10 Downing St",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "phone": "+44 20 7925 0918",
        "email": "sender@example.com",
        "company": "London Logistics"
    },
    "address_to": {
        "object_purpose": "PURCHASE",
        "name": "Northern Ireland Recipient",
        "street1": "123 Causeway Road",
        "city": "Bushmills",
        "state": "County Antrim",
        "zip": "BT57 8SU",
        "country": "GB",
        "phone": "+44 28 2073 0918",
        "email": "recipient.ni@example.com"
    },
    "customs_declaration": {
        "contents_type": "MERCHANDISE",
        "non_delivery_option": "RETURN",
        "certify": true,
        "certify_signer": "Saurabh Sharan",
        "incoterm": "DDU",
        "items": [
            {
                "description": "T-shirt",
                "quantity": 10,
                "net_weight": "2",
                "mass_unit": "lb",
                "value_amount": "200",
                "value_currency": "USD",
                "tariff_number": "1",
                "sku_code": "TS-WHT-MD",
                "origin_country": "GB"
            }
        ]
    },
    "parcels": {
        "length": 5,
        "width": 5,
        "height": 5,
        "distance_unit": "in",
        "weight": 2,
        "mass_unit": "lb"
    }
}'

```

### Response Sample

```json theme={null}
{
    "object_id": "ecfa8357e93f40b4a5b247a4794208a6",
    "object_created": "2025-08-05T05:11:50.747Z",
    "object_updated": "2025-08-05T05:11:51.633Z",
    "object_owner": "expn-prod-test@goshippo.com",
    "test": false,
    "metadata": "",
    "messages": [],
    "extra": {},
    "order": null,
    "carrier_accounts": [
        "*****"
    ],
    "address_from": {
        "name": "London Sender",
        "street1": "10 Downing St",
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "street_no": "",
        "phone": "00442079250918",
        "email": "sender@example.com",
        "company": "London Logistics",
        "is_residential": null,
        "test": false,
        "object_id": "c81c84d3206a42138378a28bc6a37c21",
        "is_complete": true,
        "validation_results": {}
    },
    "address_to": {
        "name": "Northern Ireland Recipient",
        "street1": "123 Causeway Road",
        "street2": "",
        "street3": "",
        "city": "Bushmills",
        "state": "County Antrim",
        "zip": "BT57 8SU",
        "country": "GB",
        "street_no": "",
        "phone": "00442820730918",
        "email": "recipient.ni@example.com",
        "company": "",
        "is_residential": null,
        "test": false,
        "object_id": "9523b3754f504c73810eb3ec6520ee79",
        "is_complete": true,
        "validation_results": {}
    },
    "parcels": [
        {
            "object_owner": "expn-prod-test@goshippo.com",
            "object_state": "VALID",
            "mass_unit": "lb",
            "template": null,
            "extra": {},
            "metadata": "",
            "test": false,
            "object_id": "76bba84bd1824a9fa1b57f1d4d27ef8e",
            "object_created": "2025-08-05T05:11:50.747Z",
            "object_updated": "2025-08-05T05:11:50.747Z",
            "length": "5.0000",
            "width": "5.0000",
            "height": "5.0000",
            "distance_unit": "in",
            "weight": "2.0000",
            "line_items": []
        }
    ],
    "status": "SUCCESS",
    "shipment_date": "2025-08-05T05:11:50.747Z",
    "address_return": {
        "name": "London Sender",
        "street1": "10 Downing St",
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "street_no": "",
        "phone": "00442079250918",
        "email": "sender@example.com",
        "company": "London Logistics",
        "is_residential": null,
        "test": false,
        "object_id": "c81c84d3206a42138378a28bc6a37c21",
        "is_complete": true,
        "validation_results": {}
    },
    "rates": [
        {
            "object_id": "32444e5afe5c4d5fa44de02e4b56870d",
            "object_created": "2025-08-05T05:11:51.609Z",
            "object_owner": "expn-prod-test@goshippo.com",
            "shipment": "ecfa8357e93f40b4a5b247a4794208a6",
            "amount": "2.96",
            "currency": "GBP",
            "amount_local": "2.96",
            "currency_local": "GBP",
            "attributes": [
                "FASTEST"
            ],
            "provider": "Royal Mail SF",
            "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/royal_mail_sf.png",
            "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/royal_mail_sf.png",
            "arrives_by": null,
            "duration_terms": "Two business days.",
            "messages": [],
            "carrier_account": "aa79df9091b44e03a5de1538585fdd88",
            "zone": null,
            "test": false,
            "servicelevel": {
                "name": "Tracked 48 for Post Office Drop",
                "token": "royal_mail_sf_tracked_48_for_post_office_drop",
                "terms": "{\"base_price\": 2.76, \"vat\": 0.00, \"dropoff_surcharge\": 0, \"currency\": \"GBP\", \"total_price\": 2.76}",
                "extended_token": "royal_mail_sf_tracked_48_for_post_office_drop",
                "display_name": null,
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "included_insurance_price": null
        }
    ],
    "alternate_address_to": null,
    "customs_declaration": {
        "object_owner": "expn-prod-test@goshippo.com",
        "object_state": "VALID",
        "certify": true,
        "certify_signer": "Saurabh Sharan",
        "non_delivery_option": "RETURN",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "aes_itn": "",
        "incoterm": "DDU",
        "eel_pfc": "",
        "b13a_filing_option": "",
        "b13a_number": "",
        "disclaimer": "",
        "notes": "",
        "metadata": "",
        "test": false,
        "is_vat_collected": null,
        "object_id": "4ab606eef0f74c479d4df6e47963212b",
        "object_created": "2025-08-05T05:11:50.747Z",
        "object_updated": "2025-08-05T05:11:50.747Z",
        "items": [
            "e3a0bcbb45044228b127d7efa3ee5d2a"
        ],
        "invoiced_charges": null,
        "address_importer": null,
        "duties_payor": null,
        "exporter_identification": null
    }
}
```

Once you have created your shipment, proceed to [Step 3: Purchase label](/carriers/integration-guides/royal-mail-tracked/purchase-label).


# Purchase label
Source: https://docs.goshippo.com/carriers/integration-guides/royal-mail-tracked/purchase-label

Purchase a Royal Mail Tracked shipping label by submitting a rate object ID to the Shippo transactions endpoint.

This is a 2nd step of the label purchase flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided ‘rate’.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/transactions/
```

## Purchase from created Shipment

This is a flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided `rate`.

### Request Payload

| Parameter           | Description                                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rate\*              | `object_id` of the rate object we get in the [create shipments call response](/carriers/integration-guides/royal-mail-tracked/create-shipment#response-sample). |
| label\_file\_type\* | Allowed values: `PDF`, `PDF_A4`                                                                                                                                 |
| async               | Set to true if you want to poll for the result and receive faster response                                                                                      |

Note: Parameters with an \* are mandatory

### Example

#### Request Sample

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>’ \
--header 'Content-Type: application/json' \
--data-raw '{
    "rate": "32444e5afe5c4d5fa44de02e4b56870d",
    "async": false,
    "label_file_type": "PDF"
}'

```

#### Response Sample

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": “2025-08-05T21:43:41.829Z”,
   "object_updated":“2025-08-05T21:43:41.829Z”,
   "object_id": "cbc1a12243db44b9ae56ef3ca502b8c3",
   "object_owner": expn-prod-test@goshippo.com",
   "test": false,
   "rate": "32444e5afe5c4d5fa44de02e4b56870d",
   "tracking_number": "TQ966044837GB",
   "tracking_status": "PRE_TRANSIT",
   "eta": null,
   "tracking_url_provider": "",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "bf276a9f955f43e7b7a75345687b9f4d",
   "billing": {
       "payments": []
   },
   "qr_code_url": null
}
```

## Sample Label

Below is a sample PDF label for a Royal Mail C2C MCA Tracked 48 for Post Office Drop.

<img alt="" />

After you have created your label and shipped your package, you may request tracking status updates by following the process described in [Step 4: Track](/carriers/integration-guides/royal-mail-tracked/track).


# Terms Acceptance
Source: https://docs.goshippo.com/carriers/integration-guides/royal-mail-tracked/terms-and-conditions-acceptance

Accept Royal Mail Terms and Conditions before your first label purchase via the Shippo Web App or API Portal.

A shipper using Royal Mail services needs to acknowledge and accept Royal Mail's Terms and Conditions before their first label purchase. This can be accomplished either via the [Shippo Web App](https://app.goshippo.com), or through the [Shippo API Portal](https://portal.goshippo.com/).

### Terms to be accepted

* Postal Service Act 2000 │ Royal Mail Group Ltd

* Click & Drop™ Terms and Conditions

* Rates for Royal Mail MCA will be sent as part of the POST /shipment response.

<Info>
  **Note**

  Label Purchase will be blocked by Shippo until the terms have been accepted.
</Info>

Once you have accepted the Terms and Conditions, proceed to [Step 2: Create shipment](/carriers/integration-guides/royal-mail-tracked/create-shipment).


# Tracking
Source: https://docs.goshippo.com/carriers/integration-guides/royal-mail-tracked/track

Track Royal Mail Tracked shipments and receive webhook notifications for status changes using the Shippo Tracking API.

You can register your webhook(s) for a Shipment (and request the current status at the same time) by POSTing to the tracking endpoint. This way Shippo will send HTTP notifications to your track\_updated webhook(s) whenever the status changes.

## HTTP Method

POST

## URL

```
https://api.goshippo.com/tracks/
```

### Request Payload

| Parameter in POST Data | Description                                                                                                                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| carrier\*              | `royal_mail_sf`                                                                                                                                                                                                  |
| tracking\_number\*     | `tracking_number` value of the transaction response, we get in the transaction call response. [create shipments call response](/carriers/integration-guides/royal-mail-tracked/create-shipment#response-sample). |
| metadata               | Additional metadata to associate with this tracking request.                                                                                                                                                     |

## Response Code

200 OK

### Request Example

```shell cURL theme={null}
curl https://api.goshippo.com/tracks/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d carrier="royal_mail_sf" \
    -d tracking_number="TQ966044837GB" \
    -d metadata="Order 000123"
```

### Response Example

```json theme={null}
{
    "tracking_number": "TQ966044837GB",
    "carrier": "royal_mail_sf",
    "servicelevel": {
        "name": null,
        "token": null
    },
    "transaction": "5748cf036bce476c9ed3c92a9270edd7",
    "address_from": {
        "city": "",
        "state": "",
        "zip": "",
        "country": "GB"
    },
    "address_to": {
        "city": "",
        "state": "",
        "zip": "",
        "country": "GB"
    },
    "eta": null,
    "original_eta": null,
    "metadata": null,
    "test": false,
    "tracking_status": {
        "status_date": "2025-07-24T10:32:52Z",
        "status_details": "Delivered to Safeplace by",
        "location": null,
        "substatus": {
            "code": "delivered",
            "text": "Package has been delivered.",
            "action_required": false
        },
        "object_created": "2025-07-24T12:57:38.73Z",
        "object_updated": "2025-07-24T12:57:38.73Z",
        "object_id": "f379269f8c584d278d8abd9a9e2bd2ff",
        "status": "DELIVERED"
    },
    "tracking_history": [
        {
            "status_date": "2025-07-18T23:39:04Z",
            "status_details": "Sender despatching item",
            "location": null,
            "substatus": {
                "code": "information_received",
                "text": "Information about the package received.",
                "action_required": false
            },
            "object_created": "2025-07-18T23:14:19.94Z",
            "object_updated": "2025-07-19T03:42:02.857Z",
            "object_id": "db068dfd371e403ba65cf8c45adff4bc",
            "status": "PRE_TRANSIT"
        },
        {
            "status_date": "2025-07-19T16:03:12Z",
            "status_details": "Accepted at Parcelshop",
            "location": null,
            "substatus": {
                "code": "package_accepted",
                "text": "Package has been accepted into the carrier network for delivery.",
                "action_required": false
            },
            "object_created": "2025-07-19T16:53:22.097Z",
            "object_updated": "2025-07-19T16:53:22.097Z",
            "object_id": "5e47dc859ac24476b6dfcf876abc9c27",
            "status": "TRANSIT"
        },
        {
            "status_date": "2025-07-22T01:36:18Z",
            "status_details": "Item Received",
            "location": null,
            "substatus": {
                "code": "information_received",
                "text": "Information about the package received.",
                "action_required": false
            },
            "object_created": "2025-07-22T05:08:27.592Z",
            "object_updated": "2025-07-22T05:08:27.592Z",
            "object_id": "2f048f514f8b474aa28fcb99302cbffc",
            "status": "TRANSIT"
        },
        {
            "status_date": "2025-07-23T17:13:45Z",
            "status_details": "Item Received",
            "location": null,
            "substatus": {
                "code": "delivery_scheduled",
                "text": "Package is scheduled for delivery.",
                "action_required": false
            },
            "object_created": "2025-07-23T19:48:10.325Z",
            "object_updated": "2025-07-23T19:48:10.325Z",
            "object_id": "c005bb9f1574466284b5372676933cea",
            "status": "TRANSIT"
        },
        {
            "status_date": "2025-07-23T17:14:20Z",
            "status_details": "Item Received",
            "location": null,
            "substatus": {
                "code": "package_accepted",
                "text": "Package has been accepted into the carrier network for delivery.",
                "action_required": false
            },
            "object_created": "2025-07-23T19:48:10.325Z",
            "object_updated": "2025-07-23T19:48:10.325Z",
            "object_id": "d4af04d33e734623b4476215fdc89573",
            "status": "TRANSIT"
        },
        {
            "status_date": "2025-07-24T07:49:07Z",
            "status_details": "Due to be delivered today",
            "location": null,
            "substatus": {
                "code": "delivery_scheduled",
                "text": "Package is scheduled for delivery.",
                "action_required": false
            },
            "object_created": "2025-07-24T08:40:11.324Z",
            "object_updated": "2025-07-24T08:40:11.324Z",
            "object_id": "e1412c07a0954efea54c544634c00646",
            "status": "TRANSIT"
        },
        {
            "status_date": "2025-07-24T10:32:52Z",
            "status_details": "Delivered to Safeplace by",
            "location": null,
            "substatus": {
                "code": "delivered",
                "text": "Package has been delivered.",
                "action_required": false
            },
            "object_created": "2025-07-24T12:57:38.73Z",
            "object_updated": "2025-07-24T12:57:38.73Z",
            "object_id": "f379269f8c584d278d8abd9a9e2bd2ff",
            "status": "DELIVERED"
        }
    ],
    "messages": []
}
```


# UPS Mail Innovations
Source: https://docs.goshippo.com/carriers/ups-mail-innovations

Ship lightweight parcels and letters using UPS Mail Innovations through your Shippo integration for US domestic shipments.

Shipping lightweight parcels, flat packages, and letters is generally reserved for local mail service.
You can ship these lighter weight packages through your Shippo integration using [UPS Mail Innovations](https://www.ups.com/us/en/supplychain/logistics-solutions/mail-innovations.page).

UPS Mail Innovations is a shipping and mailing service offered by UPS that utilizes a combination of UPS's ground network and the United States Postal Service (USPS) for delivery. It is designed for small to medium-sized businesses that need to ship a significant volume of lightweight and flat packages.

You can ship the following with UPS Mail Innovations

* Letters and documents
* Flat packages (up to 130 inches in combined length, width, and height)
* Packages weighing less than 1 pound

<Info>
  **Note**

  Shippo support UPS Mail Innovations for US domestic shipments only.
</Info>

## Create a lightweight shipment using the Shippo API

### Find your UPS account object ID

If you have already identified the object ID of your UPS account, move to [step 2](#update-your-ups-account).
To find the object ID of your UPS account, following the example below.

**Request:**

```shell cURL theme={null}
curl https://api.goshippo.com/carrier_accounts \
 -H "Authorization: ShippoToken <API_TOKEN>"
```

**Response:**

```json Response theme={null}

{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
    {
      "account_id": "56782",
      "active": true,
      "carrier": "UPS",
      "parameters": {
        "account_number": "94567e",
        ….
      },
      "is_shippo_account": false,
      "metadata": "string",
      "object_id": "6aa34d5f6865448fbb1ee93636e98999",
      "object_owner": "bob22@gmail.com",
      "test": false
    },
  ]
}
```

### Update your UPS account

Mail Innovations is an additional service that must be enabled by UPS. Contact your UPS account representative to get the following account details.

* customer ID
* customer GUID

To enable Mail Innovations, use the following example to update your existing UPS account.

<Info>
  **note**

  Alternatively, instead of updating your existing UPS account to enable Mail Innovations, you may choose to create a new UPS account with Mail Innovations already enabled.
</Info>

**Request:**

```shell cURL theme={null}
curl https://api.goshippo.com/carrier_accounts/6aa34d5f6865448fbb1ee93636e98999/ \
-X PUT  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-d parameters='{
       "cost_center": "",
       "password": "x99pass",
       "account_number": "94567e",
       "usps_endorsement": "",
       "surepost": "",
       "customer_id": "1234",
       "customer_guid": "1234-abcde"
}'
```

**Response:**

```json Update account response theme={null}
{
    "object_id": "16786b4db03d4d97bc8a213557f1c1e0",
    "object_owner": "bob22@gmail.com",
    "carrier": "ups",
    "account_id": "56782",
    "parameters": {
       "cost_center": "",
       "password": "****",
       "account_number": "94567e",
       "usps_endorsement": null,
       "surepost": "",
       "customer_id": "8899",
       "customer_guid": "7896"
    },
    "test": false,
    "active": true
}
```

Use the returned `object_id` in [step 2](#get-ups-mail-innovations-rates) to retrieve rates only from UPS.

### Get UPS Mail Innovations rates

To get rates for a UPS Mail Innovations shipment, create a shipment specifying UPS as your preferred carrier by setting `carrier_accounts` to the `object_id` returned from [step 1](#update-your-ups-account).

The Shippo API will only return Mail Innovations rates under the following conditions.

* You must not specify a parcel template.
* You must specify the dimensions of the your parcel (`length`, `width`, `height`) and `weight`.
* You will only receive a rate from UPS Mail Innovations if your dimensions fit the required criteria of packages weighing less than 1 pound and having dimensions of less than 130 inches in combined length, width, and height.
* If your package is non-rectangular (for example, [rolls or tubes](https://www.ups.com/assets/resources/webcontent/supplychain/media/Qualified-Domestic-Mail.pdf)), you must specify by setting `parcel.metadata` to `Non-rectangular`.

Use the following example to get a Mail Innovations rate.

**Request:**

```shell cURL theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "object_purpose": "PURCHASE",
    "address_from": {
      "object_purpose": "PURCHASE",
      "name": "Mr. Hippo",
      "company": "Lampeez",
      "street1": "2640 Northaven Road",
      "street2": "Suite 107",
      "city": "Dallas",
      "state": "TX",
      "zip": "75229",
      "country": "US",
      "phone": "6825973270",
      "email": "bob22@gmail.com"
    },
    "address_to": {
      "object_purpose": "PURCHASE",
      "name": "Mrs. Hippo",
      "company": "Dean Lytle",
      "street1": "27 Holly Pl",
      "street_no": "",
      "street2": "",
      "city": "Bracey",
      "state": "VA",
      "zip": "23919",
      "country": "US",
      "phone": "4346364281",
      "email": "dlytle4087@mail.com",
      "metadata": "Customer ID 123456"
    },
    "parcels": [{
      "length": "12",
      "width": "10",
      "height": "5",
      "distance_unit": "in",
      "weight": "0.5",
      "mass_unit": "lb"
    }],
    "metadata": "test",
    "async": false,
    "carrier_accounts": ["16786b4db03d4d97bc8a213557f1c1e0"]
}'
```

**Response:**

```json Response theme={null}
"provider": "UPS",
"provider_image_75": "https://cdn2.goshippo.com/providers/75/UPS.png",
"provider_image_200": "https://cdn2.goshippo.com/providers/200/UPS.png",
"servicelevel": {
    "name": "Mail Innovations Parcel",
    "token":"ups_mail_innovations_parcel",
    "terms": "",
},
```

## Mail Innovations Service level tokens

| Token                                  | Service level name             |
| -------------------------------------- | ------------------------------ |
| ups\_mail\_innovations\_bpm\_flat      | Mail Innovations BPM Flat      |
| ups\_mail\_innovations\_bpm\_parcel    | Mail Innovations BPM Parcel    |
| ups\_mail\_innovations\_irregular      | Mail Innovations Irregular     |
| ups\_mail\_innovations\_media\_mail    | Mail Innovations Media Mail    |
| ups\_mail\_innovations\_parcel         | Mail Innovations Parcel        |
| ups\_mail\_innovations\_standard\_flat | Mail Innovations Standard Flat |


# API Quickstart Guide
Source: https://docs.goshippo.com/guides/api-quickstart

Make your first Shippo API call by creating an address, setting up your token, and testing a request.

Follow this guide to make your first Shippo API call. In this guide, you will learn how to create an address using the Shippo API.

<Tip>
  Building shipping for multiple merchants?

  A single API account works great for one business. If you're building a platform where other businesses will ship through your integration, there's a different setup that handles per-merchant billing, carrier accounts, and reporting cleanly.

  [See which integration path is right for you →](/guides/integration-paths)
</Tip>

## Generate your API Token

Follow the [Authentication guide](/guides/authentication) to generate your API Token.

<Info>
  **Note**

  When learning about and testing the Shippo API, we recommend using the [test token](/guides/testing).
  Using your test token means all the calls you make to the Shippo API are free.
</Info>

## Install the client library for your language

<CodeGroup>
  ```shell title="cURL" theme={null}
  # No library needed for cURL
  ```

  ```python title="Python" theme={null}
  pip install shippo
  ```

  ```php title="PHP" theme={null}
  // Follow the steps in 
  // https://github.com/goshippo/shippo-php-client
  ```

  ```javascript title="Node.js" theme={null}
  npm install shippo
  ```

  ```java title="Java" theme={null}
  // Java
  npm install shippo
  ```

  ```cs title="C#" theme={null}
  dotnet add package Shippo
  ```

  ```other title="Other libraries" theme={null}
  // For a full list of supported libraries, review our client libraries page
  // https://docs.goshippo.com/guides/client-libraries
  ```
</CodeGroup>

See our [client libraries](/guides/client-libraries) page for more details.

## Make your first API call

To make sure everything is working, make a simple call to create a new address in your Shippo account.

You must replace `<API_TOKEN>` with the token you copied from [Step 1](#generate-your-api-token).

<CodeGroup>
  ```shell title="cURL" theme={null}
  curl https://api.goshippo.com/addresses/ \
     -H "Authorization: ShippoToken <API_TOKEN>" \
     -d name="Shawn Ippotle" \
     -d company="Shippo" \
     -d street1="215 Clayton St." \
     -d street2="" \
     -d city="San Francisco" \
     -d state="CA" \
     -d zip=94117 \
     -d country="US" \
     -d phone="+1 555 341 9393" \
     -d email="shippotle@shippo.com"\
     -d is_residential=True\
     -d metadata="Customer ID 123456"
  ```

  ```python title="Python" theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  shippo_sdk.addresses.create(
      components.AddressCreateRequest(
          name="Shawn Ippotle",
          company="Shippo",
          street1="215 Clayton St.",
          city="San Francisco",
          state="CA",
          zip="94117",
          country="US", # iso2 country code
          phone="+1 555 341 9393",
          email="shippotle@shippo.com"
      )
  )
  ```

  ```php title="PHP" theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_TOKEN>");

  // Create address object
  $fromAddress = Shippo_Address::create( array(
      "name" => "Shawn Ippotle",
      "company" => "Shippo",
      "street1" => "215 Clayton St.",
      "city" => "San Francisco",
      "state" => "CA",
      "zip" => "94117",
      "country" => "US",
      "phone" => "+1 555 341 9393",
      "email" => "shippotle@shippo.com" 
  ));
  ```

  ```typescript title="TypeScript" theme={null}
  // Create address object
  const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>'});
  const addressFrom = await shippo.addresses.create({
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US", // iso2 country code
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com",
  });
  ```

  ```java title="Java" theme={null}
  Shippo.setApiKey('<API_TOKEN>');

  HashMap<String, Object> addressMap = new HashMap<String, Object>();
  addressMap.put("name", "Mr. Hippo");
  addressMap.put("company", "Shippo");
  addressMap.put("street1", "215 Clayton St.");
  addressMap.put("city", "San Francisco");
  addressMap.put("state", "CA");
  addressMap.put("zip", "94117");
  addressMap.put("country", "US");
  addressMap.put("phone", "+1 555 341 9393");
  addressMap.put("email", "support@goshipppo.com");

  Address createAddress = Address.create(addressMap);
  ```

  ```cs title="C#" theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_TOKEN>");
  Address address = await sdk.Addresses.CreateAsync(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Company = "Shippo",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  ```

  ```other title="Other libraries" theme={null}
  // For a full list of supported libraries, review our client libraries page
  // https://docs.goshippo.com/guides/client-libraries
  ```
</CodeGroup>

If your request to create a new address was a success, the response should look like the following. If you don't get a response like this, check your code and make sure your API token is correct.

```json theme={null}
{
   "is_complete": true,
   "object_created":"2022-07-09T02:19:13.174Z",
   "object_updated":"2022-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@shippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@shippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}
```

## Next steps

You now know how to make API calls using the Shippo API. Your next step is to create your [first shipping label](/guides/generate-shipping-label).

You can also start exploring our [API reference](/api-reference/addresses/list-all-addresses) to learn about all the Shippo API features.


# Authentication
Source: https://docs.goshippo.com/guides/authentication

Learn how to authenticate Shippo API requests using live and test API keys, and manage your tokens securely.

Shippo authenticates your API requests using your account’s API keys.

<Info>
  **note**

  If your request does not include a key, or includes a deleted or expired key, the Shippo API returns a `401 Unauthorized` error with the following responses, depending on the nature of the error.

  ```json theme={null}
  {
      "detail": "Token does not exist"
  }
  ```

  Or

  ```json theme={null}
  {
      "detail": "Authentication credentials were not provided."
  }
  ```
</Info>

## Test mode and live mode

You can make Shippo API calls in either test mode or live mode. When you use test mode, you have access to test data and can make test calls. When you use live mode, you have access to live data and can make live calls (like purchasing a label). Each mode has its own set of API keys.

| Type      | When to use                                                                                                                                                                                                           | How to use                                                                              | Considerations                                                                                                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test mode | As you test and build your Shippo integration, use test mode with your test keys. In test mode, you can use all of the Shippo services like retrieving shipping rates and creating test labels without being charged. | Use your API test token for `Authentication` in [your API calls](#use-your-secure-key). | Rates requested in test mode may differ from actual rates in live mode. Data is not shared between test account and live account.<br /><br /> For a full list of considerations, review our [testing guide](/guides/testing#notes-about-test-mode) |
| Live mode | When your integration is ready for production use live mode with your live tokens. In live mode, you can generate shipping rates and purchase real shipping labels.                                                   | Use you API live token for `Authentication` in [your API calls](#use-your-secure-key)   | Your account will be charged for purchasing labels.                                                                                                                                                                                                |

## Get your API keys

### Create your free Shippo account

If you already have a Shippo account, skip ahead to [Step 2](#generate-your-secure-key).

In your browser, open the address [https://apps.goshippo.com/join](https://apps.goshippo.com/join). Enter your name, email, a secure password, and click **Get Started**.

Follow the prompts to complete your registration.

### Generate your secure key

Login to the [Shippo API portal](https://portal.goshippo.com/api-config/api) using your Shippo credentials.

<img alt="generate token UI" />

In the **API Configuration** menu, select **Developer keys**.
In **Developer Keys**, there are two options.
**Live keys** and **Test keys**. Use **Live keys** for production ready use of the Shippo API. For testing and development, use the [Test key](/guides/testing).

* Click **Create new live key** for a live key.
  * Live keys begin with `shippo_live_`.
* Click **Create new test key** for a test key.
  * Test keys begin with `shippo_test_`.

Copy your API key and click **Close**.

<Info>
  **Note**

  You can only see your full API key once. Store it in a secure place. If you lose your API key, you can generate a new one.
</Info>

<Warning>
  **Warning**

  These keys give direct access to your Shippo account. You must store these securely. If you think your key has been compromised, use the dashboard to delete it and generate a new key.
</Warning>

### Use your secure key

To use your secure key, make an API call replacing `<API_TOKEN>` with the key you have generated.

```shell theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -H "Content-Type: application/json"\
    -d '{...}'
```


# Authentication using JWT
Source: https://docs.goshippo.com/guides/authentication-using-jwt

Generate JWTs to securely authenticate client-side apps with the Shippo API for white label or gray label integrations.

For server-side applications where you can keep API keys secure, follow our [Authentication](/guides/authentication) guide.
For your client-side applications, we recommend using a JWT to securely authenticate. Following this guide to generate a JWT for your application.

<Info>
  **note**

  Depending on the path you choose for integration, there is a different set of instructions. Refer to our [integration paths](/guides/integration-paths) for more details.
</Info>

## Generate a JWT for an eCommerce store

If you have an eCommerce store that you want to add shipping to, you can generate a JWT using your own Shippo API key.
Follow this example that uses the `embedded/authz/` endpoint to create a JWT.

```shell JWT for eCommerce merchant request theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

```json JWT for eCommerce merchant response theme={null}
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}
```

The `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

## Generate a JWT for a white label integration

If you have not already, review our guide on [Shippo Platform accounts](/platform-accounts/platform-accounts). You must have a Platforms account to create and use Managed Shippo Accounts.

If you do not know your customer's Shippo Account ID, refer to this guide to [retrieve your user's Shippo Account ID](/shipping-elements/auth#1-retrieve-your-users-shippo-account-id).

To generate a JWT for a Managed account, call the `embedded/authz/` endpoint and set the `object_id` of your customers Shippo Account ID to the `SHIPPO-ACCOUNT-ID` in the header of the call.

```shell JWT for white label request theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'SHIPPO-ACCOUNT-ID: e0b382dc7d754c0ca6358c09d5d2bdf7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

```json JWT for white label response theme={null}
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}
```

The `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

## Generate a JWT for a gray label integration

If you have not already, follow the steps in our [guide to request your OAuth key](/o-auth-integrations/o-auth) and get access to a Bearer Token.

There are 2 ways you can generate your own JWT for gray label integration.

### 1. Direct Authorization API

```shell JWT for gray label request theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: Bearer <OAUTH_BEARER_TOKEN> \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

```json JWT for gray label response theme={null}
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}

```

The `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

### 2. User Server Side Remote Procedure Call to generate JWT

```shell theme={null}
service user {
  rpc DirectAuthorization(DirectAuthorizationRequest) : DirectAuthorizationResponse
}

message DirectAuthorizationRequest {
 context
 requestor: // integration user id
 requested_subject: // alice's id
 token_type: 'jwt'
}
```

```json Response theme={null}
message DirectAuthorizationResponse {
  token: 
  // encoded jwt
  expires: 
  //unix timestamp representing when the token expires
}
```

The `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

## Use your JWT

JWT works the same as an API token. To test your generated JWT, call the [list all carrier parcel templates](/api-reference/carrier-parcel-templates/list-all-carrier-parcel-templates) endpoint. Remember to replace `<JWT_TOKEN>` with the token you have generated.

```shell Use JWT request theme={null}
curl --location --request GET https://api.goshippo.com/parcel-templates  \
    --header 'Authorization: JWT <JWT_TOKEN>' \
    --header 'Content-Type: application/json'
```

```json Use JWT response theme={null}
[
  {
    "name": "FedEx® Small Box (S1)",
    "token": "FedEx_Box_Small_1",
    "carrier": "FedEx",
    "is_variable_dimensions": false,
    "length": "12.375",
    "width": "10.875",
    "height": "1.5",
    "distance_unit": "in"
  }
]
```


# SDKs
Source: https://docs.goshippo.com/guides/client-libraries

Find Shippo SDKs for Python, Node.js, Java, C#, PHP, and Go, plus our Postman collection for API testing.

<Info>
  **Note**

  We are currently updating each of our client libraries. Refer to each library source for the latest information.
</Info>

While you can use Shippo's shipping API by making direct HTTP requests to our servers, we provide SDKs for our API to make it easier to access them from a list of supported languages. You can find out more about the available libraries for the language of choice below.

***

### <img alt="Python logo" /> Python

You can install our Python SDK using pip. The source code is available on [GitHub](https://github.com/goshippo/shippo-python-sdk).

```python theme={null}
pip install shippo
```

***

### <img alt="Node logo" /> Node.JS

The Node client library can be installed via [npm](https://www.npmjs.com/package/shippo). The source code is available on [GitHub](https://github.com/goshippo/shippo-javascript-sdk).
Supported runtimes are listed [here](https://github.com/goshippo/shippo-javascript-sdk/blob/main/RUNTIMES.md).

```node theme={null}
npm install shippo
```

***

### <img alt="Java logo" /> Java

The Java client library can be installed through different methods
The source code and all installation methods are available on [GitHub](https://github.com/goshippo/shippo-java-sdk).
The Java package is available in [Maven central repository](https://central.sonatype.com/artifact/com.goshippo/shippo-sdk).

```
pkg:maven/com.goshippo/shippo-sdk@latest
```

***

### <img alt="C sharp logo" /> C\#

You can install our C# SDK using [NuGet](https://www.nuget.org/packages/Shippo/).
The source code is available on [GitHub](https://github.com/goshippo/shippo-csharp-sdk).

```cs C# theme={null}
dotnet add package Shippo
```

***

### <img alt="PHP logo" /> PHP

The PHP client library can be installed through different methods. The source code and all installation methods are available on [GitHub](https://github.com/goshippo/shippo-php-client).

***

## Community-maintained Libraries

### <img alt="Go logo" /> Go

The Go client library was built by [Daniel Kang](https://github.com/d5). The source code and installation methods are available on [GitHub](https://github.com/d5/go-shippo).

## Postman

### <img alt="Postman logo" /> Shippo Postman Collection

[Postman](https://www.getpostman.com/) is an app for easy RESTful API exploration. Use the Shippo Postman Collection to quickly and easily test API requests during development.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5%26entityType%3Dcollection%26workspaceId%3Da131fa9b-fc39-440e-93bb-2586e9e1eb93)


# Generate your first label
Source: https://docs.goshippo.com/guides/generate-shipping-label

Create your first shipping label with the Shippo API using a two-step rate-then-purchase flow or a single API call.

<Info>
  **Note**

  If you would prefer to learn how to create your first shipping label using Postman, see our guide to create your [first shipping label using Postman](/guides/generate-shipping-label-postman).
</Info>

Use the Shippo API to programmatically create shipping labels from any supported carrier. Follow this guide to learn how to create your first label. This guide uses Shippo API objects, to learn more about these read our [API objects guide](/api-concepts/api-objects).

<Info>
  **Note**

  Before starting this guide, follow the [Authentication guide](/guides/authentication) to generate your API Token. In these guides, wherever you see `<API_TOKEN>`, replace it with you own token.

  When learning about and testing the Shippo API, we recommend using the [test token](/guides/testing). Using your test token means all the calls you make to the Shippo API are free.
</Info>

## Introduction

There are two ways to create shipping labels with the Shippo API

1. [Create a label with two API calls](#create-a-label-with-two-api-calls)

If you don't know which carrier and service you want to use, use the two API call method. This retrieves all the  available rates for your shipment. You can then choose the rate that works best for you before purchasing it.

2. [Create a label with one API call](#create-a-label-with-one-api-call)

If you already know which carrier and service you want to use, you can create a label with a single API call directly.

## Create a label with two API calls

To retrieve all available rates and create a shipping label based on one of the rates, you need to follow two simple steps:

1. Create the `shipment` object, consisting of two `address` objects (address from and address to) and at least one `parcels` object (blue objects below). The Shipment response contains the list of available Rates and their associated object IDs.
2. Create the `transaction` object. You pass your chosen `rates` object (green object below) to the transaction call. Calling the transaction endpoint purchases your label.

<img alt="Object Flow" />

<img alt="Object Flow" />

### Create a Shipment object

<img alt="Highlighted Shipment" />

<img alt="Highlighted Shipment" />

To create a [Shipment object](/api-reference/shipments/list-all-shipments), call the shipment endpoint `https://api.goshippo.com/shipments/`.

At a minimum, a shipment requires a `address_from`, `address_to`, and `parcels`.

<Info>
  **Note**

  All US addresses are automatically validated. For more information see our [Address Validation guide](/addresses/address-validation).
</Info>

**Request:**

<CodeGroup>
  ```shell title="cURL" theme={null}
  curl https://api.goshippo.com/shipments/  \
      -H "Authorization: ShippoToken <API_TOKEN>" \
      -H "Content-Type: application/json"  \
      -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
      }'
  ```

  ```Python title="Python" theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  address_from = components.AddressCreateRequest(
      name="Shawn Ippotle",
      street1="215 Clayton St.",
      city="San Francisco",
      state="CA",
      zip="94117",
      country="US"
  )

  address_to = components.AddressCreateRequest(
      name="Mr Hippo",
      street1="Broadway 1",
      city="New York",
      state="NY",
      zip="10007",
      country="US"
  )

  parcel = components.ParcelCreateRequest(
      length="5",
      width="5",
      height="5",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  shipment = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          parcels=[parcel],
          async_=False
      )
  )
  ```

  ```PHP theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_TOKEN>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'street1' => 'Broadway 1',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393'
  );

  $parcel = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $shipment = Shippo_Shipment::create( array(
      'address_from'=> $fromAddress,
      'address_to'=> $toAddress,
      'parcels'=> array($parcel),
      'async'=> false
      )
  );
  ```

  ```typescript title="TypeScript" theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const addressFrom: AddressCreateRequest  = {
      name: "Shawn Ippotle",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US"
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      street1: "Broadway 1",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
  };

  const parcel: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const parcel2: ParcelCreateRequest = {
      length: "10",
      width: "10",
      height: "10",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const shipment = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
      async: false
  });
  ```

  ```Java title="Java" theme={null}
  Shippo.setApiKey('<API_TOKEN>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");

  // Parcel
  HashMap<String, Object> parcelMap = new HashMap<String, Object>();
  parcelMap.put("length", "5");
  parcelMap.put("width", "5");
  parcelMap.put("height", "5");
  parcelMap.put("distance_unit", "in");
  parcelMap.put("weight", "2");
  parcelMap.put("mass_unit", "lb");

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("async", false);

  Shipment shipment = Shipment.create(shipmentMap);
  ```

  ```cs title="C#" theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_TOKEN>");
  AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
      }
  );
  AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Mr Hippo",
          Street1 = "Broadway 1",
          City = "New York",
          State = "NY",
          Zip = "10007",
          Country = "US",
      }
  );
  Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "5",
          Width = "5",
          Height = "5",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  Shipment shipment = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
          Async = false,
      }
  );
  ```
</CodeGroup>

The response includes the `object_id` for the `shipment`, `address_from`,`address_to`, and `parcels` as well as `rates`. These `rates` are the available shipping options for your shipment. Review the returned rates to find the one that works best for your shipment.

**Response:**

```json theme={null}
  {
  "carrier_accounts": [],
  "object_created": "2022-12-15T11:32:41.707Z",
  "object_updated": "2022-12-15T11:32:41.845Z",
  "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-12-15T11:32:41.675Z",
      "object_updated": "2022-12-15T11:32:41.741Z",
      "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-12-15T11:32:42.044Z",
    "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": []
}
```

### Create a Transaction object

<img alt="Highlighted Transaction" />

<img alt="Highlighted Transaction" />

Calling the transactions endpoint `https://api.goshippo.com/transactions`, creates a `transaction` [object](/api-reference/transactions/list-all-shipping-labels) and purchases your shipping label. Use the `object_id` of the `rates` you have chosen from your `shipment`. If your `shipment` has more than one `rates`, select the `object_id` of the rate that works best for you.

You can send an optional `label_file_type` in the transaction call. If you don’t specify this value, the API will use to the default file format, which you can set on the [settings page](https://apps.goshippo.com/settings/account).

**Request:**

<CodeGroup>
  ```shell title="cURL" theme={null}
  curl https://api.goshippo.com/transactions \
      -H "Authorization: ShippoToken <API_TOKEN>" \
      -d rate="eab0f0c5689347439a9b87f2380710e5"
      -d label_file_type="PDF"
      -d async=false
  ```

  ```Python title="Python" theme={null}
  # Get the first rate in the rates results.
  # Customize this based on your business logic.
  rate = shipment.rates[0]

  # Purchase the desired rate. 
  transaction = shippo_sdk.transactions.create(
      components.TransactionCreateRequest(
          rate=rate.object_id,
          label_file_type=components.LabelFileTypeEnum.PDF,
          async_=False
      )
  )

  # Retrieve label url and tracking number or error message
  if transaction.status == "SUCCESS":
      print(transaction.label_url)
      print(transaction.tracking_number)
  else:
      print(transaction.messages)
  ```

  ```PHP title="PHP" theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  $rate = $shipment["rates"][0];

  // Purchase the desired rate.
  $transaction = Shippo_Transaction::create( array( 
      'rate' => $rate["object_id"], 
      'label_file_type' => "PDF", 
      'async' => false ) );

  // Retrieve label url and tracking number or error message
  if ($transaction["status"] == "SUCCESS"){
      echo( $transaction["label_url"] );
      echo("\n");
      echo( $transaction["tracking_number"] );
  }else {
      echo( $transaction["messages"] );
  }
  ```

  ```typescript title="TypeScript" theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  const rate = shipment.rates[0];

  // Purchase the desired rate.
  const transaction = await shippo.transactions.create({
      rate: rate?.objectId,
      labelFileType: LabelFileTypeEnum.Pdf,
      async: false
  });
  ```

  ```Java title="Java" theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your own business logic
  Rate rate = rates.get(0);

  Map<String, Object> transactionParameters = new HashMap<String, Object>();
  transactionParameters.put("rate", rate.getObjectId());
  transactionParameters.put("async", false);
  Transaction transaction = Transaction.create(transactionParameters);

  if (transaction.getStatus().equals("SUCCESS")) {
      System.out.println(String.format("Label url : %s", transaction.getLabelUrl()));
      System.out.println(String.format("Tracking number : %s", transaction.getTrackingNumber()));
  } else {
      System.out.println(String.format("An Error has occured while generating you label. Messages : %s", transaction.getMessages()));
  }
  ```

  ```cs title="C#" theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  Rate rate = shipment.Rates[0];
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateTransactionCreateRequest(
          new TransactionCreateRequest()
          {
              Rate = rate.ObjectId,
              LabelFileType = LabelFileTypeEnum.Pdf,
              Async = false,
          }
      )
  );
  if (transaction.Status == TransactionStatusEnum.Success)
  {
      Console.WriteLine($"{transaction.LabelUrl}");
      Console.WriteLine($"{transaction.TrackingNumber}");
  }
  else
  {
      Console.WriteLine($"{transaction.Messages}");
  }
  ```
</CodeGroup>

The response is the `transaction` object that includes details about your purchased label including a link to download shipping label (`label_url`).

**Response:**

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-15T11:57:45.631Z",
    "object_updated": "2022-12-15T11:57:46.670Z",
    "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
}
```

This is a sample of a generated label.

<img alt="Sample shipping label" />

## Create a label with one API call

If you already know what service level you’ll be shipping with, you can create a shipping label in one API call through Shippo using our Instalabel feature.

<Info>
  **Note**

  Instalabel creation is available only for a select set of carriers through Shippo. To see if your carrier is supported, see our [carrier capabilities](/carriers/carrier-capabilities) page.
</Info>

Creating an Instalabel with one API call is a POST request to the Transaction endpoint with the nested shipment information, the carrier account, and the service token.

Here’s a sample call that instantly creates and returns a shipping label:

**Request:**

<CodeGroup>
  ```shell title="cURL" theme={null}
  curl https://api.goshippo.com/transactions/  \
      -H "Authorization: ShippoToken <API_Token>" \
      -H "Content-Type: application/json"  \
      -d '{
          "shipment": {
              "address_from": {
                  "name": "Mr. Hippo",
                  "street1": "215 Clayton St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94117",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "address_to": {
                  "name": "Mrs. Hippo",
                  "street1": "965 Mission St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94105",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "parcels": [{
                  "length": "5",
                  "width": "5",
                  "height": "5",
                  "distance_unit": "in",
                  "weight": "2",
                  "mass_unit": "lb"
              }]
          },
          "carrier_account": "b741b99f95e841639b54272834bc478c",
          "servicelevel_token": "usps_priority"
          }'
  ```

  ```Python title="Python" theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  address_from = components.AddressCreateRequest(
      name="Shawn Ippotle",
      company="Shippo",
      street1="215 Clayton St.",
      city="San Francisco",
      state="CA",
      zip="94117",
      country="US",
      phone="+1 555 341 9393",
      email="shippotle@shippo.com"
  )

  address_to = components.AddressCreateRequest(
      name="Mr Hippo",
      street1="Broadway 1",
      city="New York",
      state="NY",
      zip="10007",
      country="US",
      phone="+1 555 341 9393",
      email="mrhippo@shippo.com",
      metadata="Priority Customer"
  )

  parcel = components.ParcelCreateRequest(
      length="5",
      width="5",
      height="5",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  shipment = components.ShipmentCreateRequest(
      address_from=address_from,
      address_to=address_to,
      parcels=[parcel],
  )

  transaction = shippo_sdk.transactions.create(
      components.InstantTransactionCreateRequest(
          shipment=shipment,
          carrier_account="b741b99f95e841639b54272834bc478c",
          servicelevel_token="usps_priority"
      )
  )
  ```

  ```PHP theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'company' => 'Shippo',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'shippotle@shippo.com'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'company' => '',
      'street1' => 'Broadway 1',
      'street2' => '',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'mrhippo@shippo.com'
  );

  $parcel = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $shipment = array(
      'address_from'=> $fromAddress,
      'address_to'=> $toAddress,
      'parcels'=> array($parcel),
  );

  $transaction = Shippo_Transaction::create( array(
      'shipment' => $shipment,
      'carrier_account' => 'b741b99f95e841639b54272834bc478c',
      'servicelevel_token' => 'usps_priority',
  )
  );
  ```

  ```typescript title="TypeScript" theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const addressFrom: AddressCreateRequest = {
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com",
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      company: "",
      street1: "Broadway 1",
      street2: "",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
      phone: "+1 555 341 9393",
      email: "mrhippo@shippo.com",
      metadata: "Hippos dont lie"
  };

  const parcel: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const shipment: ShipmentCreateRequest = {
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
  };

  const transaction = await shippo.transactions.create({
      shipment: shipment,
      carrierAccount: "078870331023437cb917f5187429b093",
      servicelevelToken: ServiceLevelUSPSEnum.UspsPriority.valueOf()
  });
  ```

  ```Java title="Java" theme={null}
  Shippo.setApiKey('<API_Token>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");
  addressToMap.put("phone", "+1 555 341 9393");
  addressToMap.put("email", "mrhippo@goshipppo.com");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");
  addressFromMap.put("email", "mshippo@goshipppo.com");
  addressFromMap.put("phone", "+1 619 231 1515");
  addressFromMap.put("metadata", "Customer ID 123456");

  // Parcel
  HashMap<String, Object> parcelMap = new HashMap<String, Object>();
  parcelMap.put("length", "5");
  parcelMap.put("width", "5");
  parcelMap.put("height", "5");
  parcelMap.put("distance_unit", "in");
  parcelMap.put("weight", "2");
  parcelMap.put("mass_unit", "lb");

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("async", false);

  // Transaction
  HashMap<String, Object> transactionMap = new HashMap<String, Object>();
  transactionMap.put("shipment", shipmentMap);
  transactionMap.put("servicelevel_token", "usps_priority");
  transactionMap.put("carrier_account", "b741b99f95e841639b54272834bc478c");

  Transaction transaction = Transaction.create(transactionMap);

  if (transaction.getStatus().equals("SUCCESS")) {
  	System.out.println(String.format("Label url : %s",
  	 transaction.getLabelUrl()));
  	System.out.println(String.format("Tracking number : %s",
  	 transaction.getTrackingNumber()));
  } else {
  	System.out.println(String.format("An Error has occured while generating your label. Messages : %s",
  	 transaction.getMessages()));
  }
  ```

  ```cs title="C#" theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_Token>");
  AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Company = "Shippo",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Mr Hippo",
          Street1 = "Broadway 1",
          City = "New York",
          State = "NY",
          Zip = "10007",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "mrhippo@shippo.com",
          Metadata = "Priority Customer",
      }
  );
  Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "5",
          Width = "5",
          Height = "5",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  ShipmentCreateRequest shipmentCreateRequest = new ShipmentCreateRequest()
  {
      AddressFrom = addressFrom,
      AddressTo = addressTo,
      Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
  };
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateInstantTransactionCreateRequest(
          new InstantTransactionCreateRequest()
          {
              Shipment = shipmentCreateRequest,
              CarrierAccount = "b741b99f95e841639b54272834bc478c",
              ServicelevelToken = ServiceLevelUSPSEnum.UspsPriority.Value(),
          }
      )
  );
  ```
</CodeGroup>

The response is the `transaction` object that includes details about the label including a link to your shipping label `label_url`. Shippo automatically creates the corresponding `rate` object, which you can use to retrieve the `amount` of the label.

**Response:**

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-27T19:14:48.273Z",
    "object_updated": "2022-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@shippo.com",
    "was_test": false,
    "rate": {
        "object_id": "cf6fea899f1848b494d9568e8266e076",
        "amount": "5.50",
        "currency": "USD",
        "amount_local": "5.50",
        "currency_local": "USD",
        "provider": "USPS",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "usps_priority",
        "carrier_account": "078870331023437cb917f5187429b093",
    },
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "status": "UNKNOWN",
        "status_details": "",
        "status_date": "2022-12-28T12:04:04.214Z"
    },
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "eta": "2013-12-30T12:00:00.000Z",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "",
    "messages": []
}
```

## Create a label from selected carriers

Creating a `shipment` will generate rates from all carriers connected with your account (including both Shippo carrier accounts and your own carrier accounts). You can modify your API call to return rates from your selected carriers.

<img alt="alt text" />

<img alt="alt text" />

Follow our guide on [Rate shopping with carriers](/shipments/rate-shopping-with-carriers).


# Generate your first label using Postman
Source: https://docs.goshippo.com/guides/generate-shipping-label-postman

Create your first Shippo shipping label step by step using our Postman collection with video walkthroughs.

<Info>
  **Note**

  If you would prefer to learn how to create your first shipping label using cURL, see our guide to create your [first shipping label](/guides/generate-shipping-label).
</Info>

Use the Shippo API to programmatically create shipping labels from any supported carrier.
Follow this guide and videos to learn how to create your first label using our Postman collection.

<Info>
  **Note**

  Before starting this guide, follow the [Authentication guide](/guides/authentication) to generate your API Token.

  When learning about and testing the Shippo API, we recommend using the [test token](/guides/testing).
  Using your test token means all the calls you make to the Shippo API are free.
</Info>

## Introduction

To retrieve all available rates and create a shipping label based on one of the rates, you need to follow two simple steps:

1. Create the `Shipment` [object](/api-reference/shipments/create-a-new-shipment), consisting of two `Address` objects (address from and address to) and a `Parcel` object (blue objects below).
   The Shipment response contains the list of available Rates and their associated object ID.

2. Create the `Transaction` [object](/api-reference/transactions/create-a-shipping-label), i.e. the actual label, for any of the Rates from the Shipment response (green object below).

<img alt="Object Flow" />

<img alt="Object Flow" />

## Get started with Postman

If you don't already have a Postman account, [create a new account](https://identity.getpostman.com/signup?continue=https%3A%2F%2Fweb.postman.co%2F). To use Postman you will also need to [download Postman](https://www.postman.com/downloads/) or use the [online tool](https://identity.getpostman.com/login?continue=https%3A%2F%2Fweb.postman.co%2F).

This is the [link to our Postman collection](https://god.gw.postman.com/run-collection/22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5%26entityType%3Dcollection%26workspaceId%3Da131fa9b-fc39-440e-93bb-2586e9e1eb93) that you can add to your Postman workspace.

This video will help you get started if you're unfamiliar with Postman.

<iframe />

## Create Address objects

### Create a from Address object

Shippo’s API will save addresses without distinguishing the purpose of that address. You will post the address and save the object ID for reference to it. The endpoint for this is [https://api.goshippo.com/addresses/](https://api.goshippo.com/addresses/).

To make things easier, the Postman call is set up to save the object ID from this response as a variable named `FROM_ADDRESS`. This will be stored and later used for making a label purchase. The address will be tagged with Metadata to indicate this is the Home Office. This is a good simulation of how you would store and retrieve an object ID in production.

You can examine the response in the bottom section of the Postman screen. In the response you can see the object ID that was saved for this address and also see that Shippo’s address validation corrected a spelling error in the address's city.

### Create a to Address object

Just like the From Address, this step will save and validate the To Address for our shipment. The Postman call is set to save this as the `TO_ADDRESS` environment variable for the label being created.

This video will walk you through saving the To and From addresses in Postman and demonstrate saving the object IDs.

<iframe />

## Create Shipment object

A shipment is not a label. This is an important distinction to note when using the Shippo API. A shipment is the combination of To and From addresses with Parcel information. Parcel information is the size and weight of a package. To create a shipment a post request will be sent to [https://api.goshippo.com/shipments](https://api.goshippo.com/shipments).

In the Shipment response, Shippo will show you rates for all of your enabled carriers along with recommendations for best, fastest, and cheapest rates. You can also see the full addresses you stored earlier in the response. Scroll through the response and copy an object ID from one of the rates returned so this can be used to purchase a label.

## Create a Transaction object

You can now use the object ID of the rate that was saved in <img alt="step 2 icon" /> to purchase a label. This is done by sending a post call to the [https://api.goshippo.com/transactions](https://api.goshippo.com/transactions) endpoint.

In the body of the Step 4 call, replace the object ID of the rate with the one copied from Step 3 and send the call.

When examining the response you will see the id of this label, the tracking number, and the url to view or print the label.

This video will walk you through creating the `Shipment` object and purchasing the label for a chosen rate.

<iframe />


# Choosing Your Integration Path
Source: https://docs.goshippo.com/guides/integration-paths

Understand which Shippo integration model fits your product before you write your first API call.

The fastest way to get started with Shippo is a single API account. For many developers, that's exactly the right setup. But if you're building a product where multiple businesses or merchants ship through your integration, the path you choose here affects how billing, carrier management, and reporting work at scale. This guide walks you through the decision.

<Info>
  Carriers including USPS, UPS, and Canada Post **require** e-commerce marketplaces to use separate Managed Shippo accounts for each merchant. If you run a marketplace, a Platform Account is not optional.
</Info>

## Start here: what are you building?

Answer one question before you write your first API call.

<CardGroup>
  <Card title="My own business ships packages" icon="briefcase" href="/guides/api-quickstart">
    <br />

    You're a single company sending your own shipments and you are the shipper of record.

    [Use our quickstart guide →](/guides/api-quickstart)
  </Card>

  <Card title="I'm building a platform for other businesses to ship" icon="users" href="#platform-account-model">
    You're a marketplace, WMS, e-commerce platform, or other app where merchants or customers ship through your product.

    See your account model options below.
  </Card>
</CardGroup>

<h2>
  If you're a platform: choose your account model
</h2>

Platforms have two options depending on who owns the billing relationship with each merchant.

### White label (Platform Accounts)

You own the billing relationship. Shippo is invisible to your merchants. You create and manage a headless Managed Account for each merchant via the API.

When making API calls on behalf of a merchant, include their account ID in the request header: `SHIPPO-ACCOUNT-ID: <id>`

* **Billing:** You collect and manage with your shippers
* **Branding:** Fully yours, Shippo invisible
* **Merchant login:** None required
* **Best for:** Marketplaces, SaaS platforms, 3PLs

[Platform Accounts documentation →](/platform-accounts/platform-accounts)

### Gray label (OAuth)

Your merchants create their own Shippo accounts and connect via OAuth. Shippo bills them directly. You receive an OAuth token and make API calls on their behalf.

Setup requires a contact email and callback URL from you. Shippo provides an OAuth ID and secret. Merchants authorize your platform through the Shippo OAuth flow.

* **Billing:** Shippo handles directly
* **Branding:** Co-branded (Shippo visible)
* **Merchant login:** Merchants create Shippo accounts
* **Best for:** WMS, IMS, and tools where merchants want their own Shippo relationship

[OAuth documentation →](/o-auth-integrations/o-auth)

## Then: how do you want to build the UI?

This decision is separate from your account model and applies to both white label and gray label integrations.

<CardGroup>
  <Card title="Build native UI" icon="code">
    Call the Shippo API directly and build your own interface. Most flexible, most work. You own the entire experience.
  </Card>

  <Card title="Shipping Elements" icon="window-restore">
    Embed Shippo's pre-built shipping widget using a JavaScript SDK. Include one script tag, call `init()` to authenticate, and render it into your page. Shippo maintains and updates it. Supports both white and gray label.
  </Card>
</CardGroup>

## How the account structures compare

Each model has a different relationship between your platform, Shippo, and your merchants.

|                               | Direct API                                  | White Label                                                     | Gray Label (OAuth)                                              |
| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
| **Account structure**         | All shipments on your single Shippo account | Platform account with one headless Managed Account per merchant | Each merchant connects their own Shippo account via OAuth token |
| **Recommended for platforms** | No                                          | Yes                                                             | Yes                                                             |

## Quick comparison

|                                   | Direct API          | White Label                       | Gray Label (OAuth)                |
| --------------------------------- | ------------------- | --------------------------------- | --------------------------------- |
| **Who owns billing**              | You                 | You                               | Shippo (billed per merchant)      |
| **Merchant Shippo account**       | None (your account) | Managed, headless, invisible      | Merchant's own account            |
| **Shippo visible to merchants**   | N/A                 | No                                | Yes (co-branded)                  |
| **Per-merchant carrier accounts** | No — shared         | Yes                               | Yes                               |
| **Per-merchant reporting**        | No — commingled     | Yes                               | Yes                               |
| **Merchant manages Shippo login** | No                  | No                                | Yes                               |
| **Setup complexity**              | Low                 | Medium — request Platform Account | Medium — set up OAuth credentials |

<Info>
  To set up a Platform Account (white label) or OAuth credentials (gray label), [contact Shippo](https://goshippo.com/become-a-shippo-partner) or reach out to your account team. Both require a brief setup step before you can begin building.
</Info>


# MCP Server
Source: https://docs.goshippo.com/guides/mcp-server

Connect AI assistants to Shippo with the hosted Shippo MCP server: compare rates, buy labels, track packages, and validate addresses in natural language. Point your MCP client at mcp.shippo.com and sign in with your Shippo account: nothing to install, no API key to manage. Now available in the Claude and ChatGPT connector directories.

## Overview

The Shippo MCP (Model Context Protocol) Server lets AI assistants and LLMs interact with the Shippo API in natural language: compare carrier rates, buy shipping labels, track packages, validate addresses, handle customs for international shipments, and process batches.

To connect, point any MCP-compatible client at Shippo's hosted server, `https://mcp.shippo.com`, and authorize with your Shippo account. Nothing to install, no API key to manage.

In Claude (claude.ai and Claude Desktop) and in ChatGPT, you can add Shippo directly from the directory in one click, with the Shippo icon.

## What is MCP?

Model Context Protocol (MCP) is an open protocol, developed by Anthropic, that standardizes how AI applications connect to external tools and data. The Shippo MCP Server implements it, making Shippo's shipping capabilities available to MCP-compatible clients such as Claude, ChatGPT, and Cursor.

## Features

The Shippo MCP Server provides access to core Shippo API functionality:

<AccordionGroup>
  <Accordion title="Address Management">
    <ul>
      <li><strong>Validate addresses:</strong> verify and standardize shipping addresses</li>
      <li><strong>Create address records:</strong> store addresses for future use</li>
      <li><strong>Address book:</strong> manage sender and recipient addresses</li>
    </ul>
  </Accordion>

  <Accordion title="Shipping Operations">
    <ul>
      <li><strong>Create shipments:</strong> set up shipments with origin, destination, and parcel details</li>
      <li><strong>Get rates:</strong> compare shipping rates across multiple carriers</li>
      <li><strong>Generate labels:</strong> purchase shipping labels for your shipments</li>
      <li><strong>Track packages:</strong> monitor shipment status and location</li>
    </ul>
  </Accordion>

  <Accordion title="Carrier Accounts">
    <ul>
      <li><strong>List carrier accounts:</strong> view all connected carrier accounts</li>
      <li><strong>Manage carriers:</strong> add or update carrier account settings</li>
      <li><strong>Multi-carrier support:</strong> works with USPS, UPS, FedEx, DHL, and more</li>
    </ul>
  </Accordion>

  <Accordion title="International Shipping">
    <ul>
      <li><strong>Customs declarations:</strong> create customs documentation for international shipments</li>
      <li><strong>Customs items:</strong> define items for customs processing</li>
      <li><strong>Multi-country support:</strong> ship internationally with proper documentation</li>
    </ul>
  </Accordion>

  <Accordion title="Advanced Features">
    <ul>
      <li><strong>Batch operations:</strong> process multiple shipments at once</li>
      <li><strong>Pickups:</strong> schedule carrier pickups</li>
      <li><strong>Manifests:</strong> generate end-of-day manifests</li>
      <li><strong>Webhooks:</strong> set up event notifications</li>
    </ul>
  </Accordion>
</AccordionGroup>

## Connect to the hosted server

Connect any MCP-compatible client to `https://mcp.shippo.com`. The first time you use it, your client opens a Shippo sign-in window. Authorize it once and you are connected.

| Setting        | Value                            |
| -------------- | -------------------------------- |
| Server URL     | `https://mcp.shippo.com`         |
| Transport      | Remote MCP over streamable HTTPS |
| Authentication | Sign in to Shippo (OAuth)        |

<Tip>
  There is no API key to configure for the hosted server: authentication is handled by signing in to your Shippo account. The hosted server operates against your **live** Shippo account; see [Live account and charges](#live-account-and-charges).
</Tip>

**Quick add (one click).** Each button configures your client with the hosted server, `https://mcp.shippo.com`; you still complete the Shippo sign-in on first use. If your client is not listed, follow the per-client steps below.

<CardGroup>
  <Card title="Cursor" icon="arrow-up-right-from-square" href="https://cursor.com/en-US/install-mcp?name=shippo&config=eyJ1cmwiOiJodHRwczovL21jcC5zaGlwcG8uY29tIn0=" />

  <Card title="VS Code" icon="arrow-up-right-from-square" href="vscode:mcp/install?%7B%22name%22%3A%22shippo%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.shippo.com%22%7D" />

  <Card title="LM Studio" icon="arrow-up-right-from-square" href="lmstudio://add_mcp?name=shippo&config=eyJ1cmwiOiJodHRwczovL21jcC5zaGlwcG8uY29tIn0%3D" />

  <Card title="Goose" icon="arrow-up-right-from-square" href="goose://extension?name=shippo&url=https%3A%2F%2Fmcp.shippo.com" />
</CardGroup>

Claude and ChatGPT both let you add Shippo in one click from their directories; see their per-client sections below.

### Claude (claude.ai and Claude Desktop)

Shippo is a published connector in Claude's directory, so you add it by name (with the Shippo icon) rather than pasting a URL. The directory is shared across claude.ai (web), Claude Desktop, and Claude mobile, so the steps are the same on each.

<Card title="Shippo in the Claude connector directory" icon="arrow-up-right-from-square" href="https://claude.ai/directory/connectors/shippo" />

<Steps>
  <Step title="Open Connectors">
    On claude.ai, open **Customize** in the sidebar and go to **Connectors**. In Claude Desktop, open **Settings → Connectors**.
  </Step>

  <Step title="Browse the directory">
    Click **+**, choose **Browse connectors**, and find **Shippo** in the list.
  </Step>

  <Step title="Connect">
    Click **Connect** on the Shippo listing, then complete the Shippo sign-in when prompted. The connector uses the hosted server `https://mcp.shippo.com`; there is nothing to install and no API key to enter.
  </Step>
</Steps>

Team and Enterprise admins can enable Shippo for the whole organization: in **Admin settings → Connectors**, click **Browse connectors**, find **Shippo**, and add it for your organization. Enabling it lists Shippo for members but does not sign them in; each member connects it under **Customize → Connectors** and completes the Shippo sign-in on first use. On Team plans, members who cannot add connectors see a **Request** button that notifies an admin instead.

<Note>
  If you do not see Shippo in the directory (for example, if your organization limits directory connectors), you can still add it as a custom connector: click **+**, choose **Add custom connector**, name it `Shippo`, paste the server URL `https://mcp.shippo.com`, leave the advanced OAuth fields blank, and click **Add**. Same hosted server, same sign-in.
</Note>

### Claude Code

```bash theme={null}
claude mcp add --transport http shippo https://mcp.shippo.com
```

Then run `/mcp`, select the Shippo server, and complete the browser sign-in to authorize.

### ChatGPT

Shippo is available in ChatGPT's app directory, so you can add it by name instead of pasting a URL. In the ChatGPT sidebar, open the **Apps** tab, find **Shippo**, click **Connect**, and complete the Shippo sign-in. This works on free and paid plans.

<Card title="Shippo in the ChatGPT directory" icon="arrow-up-right-from-square" href="https://chatgpt.com/plugins/plugin_asdk_app_6a3be8ce7d0c81918cb8bcc8f6d0008e" />

<Note>
  If your workspace does not show Shippo in the directory (some Business and Enterprise workspaces limit which apps appear, and an admin may need to allow it first), you can still add it manually: open **Settings** and go to the connectors area (labeled **Apps**, **Connectors**, or **Plugins** depending on your plan and version; some versions require turning on a developer or advanced option first), add a connector named `Shippo` with the server URL `https://mcp.shippo.com` and **Authentication** set to **OAuth**, then complete the Shippo sign-in. Same hosted server, same sign-in.
</Note>

To use Shippo in a conversation, mention it with **@Shippo** or open the **+** menu in the message box and select **Shippo**. Then ask in natural language, for example: "What are the cheapest rates to ship a 2 lb box from San Francisco to Austin, TX?"

### Cursor

Add a remote MCP server in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json theme={null}
{
  "mcpServers": {
    "shippo": {
      "url": "https://mcp.shippo.com"
    }
  }
}
```

Cursor supports OAuth for remote MCP servers. After saving the config, open **Settings → Tools & Integrations**, find Shippo, and complete the sign-in prompt.

### Other MCP clients

Any client that supports a remote MCP server over HTTP with OAuth can connect: use the URL `https://mcp.shippo.com` and complete the Shippo authorization when prompted. The server is also listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/) as `com.shippo/shippo-mcp`, so clients with registry-based discovery can find and add it by name.

### Stdio-only clients (npm bridge)

<Warning>
  Use the bridge only when your client cannot connect to remote MCP servers. If your client supports remote MCP with OAuth, connect to `https://mcp.shippo.com` directly (see above): same account, same tools, one less moving part.
</Warning>

If your client can only launch a local MCP server (stdio), use the [`@shippo/shippo-mcp`](https://www.npmjs.com/package/@shippo/shippo-mcp) npm package. It is a thin local bridge to the same hosted server: the first request opens the Shippo sign-in in your browser, and tool discovery and execution happen on the hosted server, so its tools always match the connector above. Requires Node.js 18+.

```json theme={null}
{
  "mcpServers": {
    "shippo": {
      "command": "npx",
      "args": ["-y", "@shippo/shippo-mcp"]
    }
  }
}
```

## Skills and knowledge for AI assistants

The connector gives your assistant Shippo's **tools**, the actions above. To also give it Shippo **know-how**, so it picks the right service, formats addresses and customs data correctly, and follows shipping best practices, add Shippo's skills and reference knowledge as context.

Shippo maintains ready-to-use skills and assistant integrations in the open-source [`goshippo/ai`](https://github.com/goshippo/ai) repository:

* **Claude:** install the Shippo plugin, which bundles this MCP connector together with Shippo's skills.
  * **Claude Code:** run `/plugin marketplace add goshippo/ai`, then `/plugin install shippo@shippo`.
  * **Claude apps (claude.ai and Desktop):** download [the Shippo plugin](https://github.com/goshippo/ai/releases/latest/download/shippo-plugin.zip) from the latest release and add it in the Plugins UI. A Team or Enterprise admin can install it for everyone under **Organization settings → Plugins**.
* **ChatGPT, Cursor, and other assistants:** download the [Shippo knowledge pack](https://github.com/goshippo/ai/releases/latest/download/shippo-knowledge-pack.md) and add it as context (a Project file, a custom GPT's knowledge, or an attached document), then connect the MCP server above so the assistant can act on it.

<Tip>
  Knowledge plus the connector is the full experience: the assistant understands *how* to ship and can actually *do* it. Knowledge on its own lets it advise you and draft API requests; add the connector when you want it to fetch live rates, buy labels, or track packages.
</Tip>

## Usage examples

Once connected, you can interact with Shippo through natural language:

### Create a shipping label

```
Create a shipping label from:
123 Main St, San Francisco, CA 94105

To:
456 Market St, New York, NY 10001

Package dimensions: 10x8x6 inches, 2 lbs
```

### Track a package

```
Track package with tracking number: 1Z999AA10123456784
```

### Validate an address

```
Validate this address:
215 Clayton St, San Francisco, CA 94117
```

### Compare shipping rates

```
Get shipping rates for a 5lb package (12x10x8 inches)
from Los Angeles, CA 90001 to Chicago, IL 60601
```

Actions that buy a label or otherwise change your account ask for confirmation before they run.

## Live account and charges

The hosted MCP server authorizes your **live** Shippo account, so:

* **Read operations are free:** comparing rates and validating addresses do not charge your account, and tracking packages purchased through Shippo is free too. Tracking a package purchased *outside* Shippo is a billable action.
* **Buying a label is a live action** that charges your account. Write actions such as purchasing a label ask for confirmation before they run.

The hosted MCP server has no separate test mode. If you need test labels and mock tracking for development, use a test API key (`shippo_test_`) directly against the Shippo API, see [Testing the Shippo API](/guides/testing). Test and live data (and object IDs) are completely separate.

## Security

Requests are sent to Shippo's hosted MCP server over HTTPS, authenticated by your per-user Shippo authorization, and forwarded to the Shippo API on your behalf. There is no API key to store and no local process in the path. To disconnect, remove the Shippo connector from your client's settings and revoke access from your Shippo account if desired.

## Troubleshooting

* **Shippo isn't in your directory:** the listing may still be rolling out to your client, or your workspace limits directory connectors. Add it as a custom connector with the URL `https://mcp.shippo.com` (see the Claude or ChatGPT steps above).
* **Shippo doesn't appear in the connector or tool picker:** confirm the server was added and the Shippo sign-in completed. Reopen your client's connector settings to check its status.
* **You're asked to sign in again:** the authorization session expired. Re-authorize from the connector settings (in Claude Code, run `/mcp`).
* **The sign-in window is blocked:** allow pop-ups for your client and retry.

## Resources

* [Shippo API Documentation](/)
* [Quickstart Guide](/guides/api-quickstart)
* [Authentication](/guides/authentication)
* [MCP Protocol Specification](https://modelcontextprotocol.io/)

## Support

For questions or issues:

* [Shippo Support Portal](https://support.goshippo.com/)
* [API Status](https://status.goshippo.com/)
* [Contact Sales](https://goshippo.com/contact/)

## About Shippo

Connect with multiple carriers, get discounted shipping labels, track parcels, and much more with just one integration. You can use your own carrier accounts or take advantage of Shippo's discounted rates. Shippo simplifies carrier integrations, rate shopping, tracking, and the entire shipping workflow.


# Instalabel - single call label creation
Source: https://docs.goshippo.com/guides/single-call

Create a shipping label in one API call using Instalabel when you already know your carrier and service level.

If you already know what service level you’ll be shipping with, you can create a shipping label in one API call through Shippo using our Instalabel feature.

<Info>
  **Note**

  Instalabel creation is currently only available for a select set of carriers through Shippo. To see if your carrier is supported, see our [carrier capabilities](/carriers/carrier-capabilities) page.
</Info>

If this is your first time using Shippo, we recommend going through the [First Shipment](/guides/generate-shipping-label) tutorial to get yourself acquainted with the basic concepts.

## Setup and configuration

1. If you are using your own carrier accounts, make sure to go through the [Carrier Account](/carriers/carrier-accounts) tutorial to add your carrier credentials and connect them with Shippo first.
2. Retrieve the unique carrier account object\_id for the carrier that you’d like to use for the single-call request.
3. Take a look at our list of available service level tokens to select the one that you’d like to use for the request.

## Creating labels with one API call

Creating a label with one API call is a POST request to the Transaction endpoint with the nested shipment information, the carrier account and the service token. A sample request looks like this:

```shell cURL theme={null}
{
    "shipment": {
        "address_from": { 
            // sender address fields
        },
        "address_to": { 
            // recipient address fields
        },
        "parcels": [
            {
                // parcel fields
            }
        ],
        ... // other relevant shipment fields
    },
    "carrier_account": "<carrier-account-object-id>",
    "servicelevel_token": "<servicelevel-token>"
}
```

Here’s a sample call that instantly creates and returns a shipping label:

<CodeGroup>
  ```shell title="cURL" theme={null}
  curl https://api.goshippo.com/transactions/  \
      -H "Authorization: ShippoToken <API_Token>" \
      -H "Content-Type: application/json"  \
      -d '{
          "shipment": {
              "address_from": {
                  "name": "Mr. Hippo",
                  "street1": "215 Clayton St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94117",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "address_to": {
                  "name": "Mrs. Hippo",
                  "street1": "965 Mission St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94105",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "parcels": [{
                  "length": "5",
                  "width": "5",
                  "height": "5",
                  "distance_unit": "in",
                  "weight": "2",
                  "mass_unit": "lb"
              }]
          },
          "carrier_account": "b741b99f95e841639b54272834bc478c",
          "servicelevel_token": "usps_priority"
          }'
  ```

  ```Python title="Python" theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  address_from = components.AddressCreateRequest(
      name="Shawn Ippotle",
      company="Shippo",
      street1="215 Clayton St.",
      city="San Francisco",
      state="CA",
      zip="94117",
      country="US",
      phone="+1 555 341 9393",
      email="shippotle@shippo.com"
  )

  address_to = components.AddressCreateRequest(
      name="Mr Hippo",
      company="",
      street1="Broadway 1",
      street2="",
      city="New York",
      state="NY",
      zip="10007",
      country="US",
      phone="+1 555 341 9393",
      email="mrhippo@shippo.com",
      metadata="Hippos dont lie"
  )

  parcel = components.ParcelCreateRequest(
      length="5",
      width="5",
      height="5",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  shipment = components.ShipmentCreateRequest(
      address_from=address_from,
      address_to=address_to,
      parcels=[parcel]
  )

  transaction = shippo_sdk.transactions.create(
      components.InstantTransactionCreateRequest(
          shipment=shipment,
          carrier_account="b741b99f95e841639b54272834bc478c",
          servicelevel_token="usps_priority"
      )
  )
  ```

  ```PHP title="PHP" theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'company' => 'Shippo',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'shippotle@shippo.com'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'company' => '',
      'street1' => 'Broadway 1',
      'street2' => '',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'mrhippo@shippo.com'
  );

  $parcel = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $shipment = array(
      'address_from'=> $fromAddress,
      'address_to'=> $toAddress,
      'parcels'=> array($parcel),
  );

  $transaction = Shippo_Transaction::create( array(
      'shipment' => $shipment,
      'carrier_account' => 'b741b99f95e841639b54272834bc478c',
      'servicelevel_token' => 'usps_priority',
  )
  );
  ```

  ```typescript title="TypeScript" theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const addressFrom: AddressCreateRequest = {
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com",
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      company: "",
      street1: "Broadway 1",
      street2: "",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
      phone: "+1 555 341 9393",
      email: "mrhippo@shippo.com",
      metadata: "Hippos dont lie"
  };

  const parcel: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const shipment: ShipmentCreateRequest = {
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
  };

  const transaction = await shippo.transactions.create({
      shipment: shipment,
      carrierAccount: "078870331023437cb917f5187429b093",
      servicelevelToken: ServiceLevelUSPSEnum.UspsPriority.valueOf()
  });
  ```

  ```Java title="Java" theme={null}
  Shippo.setApiKey('<API_Token>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");
  addressToMap.put("phone", "+1 555 341 9393");
  addressToMap.put("email", "mrhippo@goshipppo.com");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");
  addressFromMap.put("email", "mshippo@goshipppo.com");
  addressFromMap.put("phone", "+1 619 231 1515");
  addressFromMap.put("metadata", "Customer ID 123456");

  // Parcel
  HashMap<String, Object> parcelMap = new HashMap<String, Object>();
  parcelMap.put("length", "5");
  parcelMap.put("width", "5");
  parcelMap.put("height", "5");
  parcelMap.put("distance_unit", "in");
  parcelMap.put("weight", "2");
  parcelMap.put("mass_unit", "lb");

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("async", false);

  // Transaction
  HashMap<String, Object> transactionMap = new HashMap<String, Object>();
  transactionMap.put("shipment", shipmentMap);
  transactionMap.put("servicelevel_token", "usps_priority");
  transactionMap.put("carrier_account", "b741b99f95e841639b54272834bc478c");

  Transaction transaction = Transaction.create(transactionMap);

  if (transaction.getStatus().equals("SUCCESS")) {
  	System.out.println(String.format("Label url : %s",
  	 transaction.getLabelUrl()));
  	System.out.println(String.format("Tracking number : %s",
  	 transaction.getTrackingNumber()));
  } else {
  	System.out.println(String.format("An Error has occured while generating your label. Messages : %s",
  	 transaction.getMessages()));
  }
  ```

  ```cs title="C#" theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_Token>");
  AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Company = "Shippo",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Mr Hippo",
          Company = "",
          Street1 = "Broadway 1",
          Street2 = "",
          City = "New York",
          State = "NY",
          Zip = "10007",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "mrhippo@shippo.com",
          Metadata = "Hippos dont lie",
      }
  );
  Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "5",
          Width = "5",
          Height = "5",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  ShipmentCreateRequest shipmentCreateRequest = new ShipmentCreateRequest()
  {
      AddressFrom = addressFrom,
      AddressTo = addressTo,
      Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
  };
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateInstantTransactionCreateRequest(
          new InstantTransactionCreateRequest()
          {
              Shipment = shipmentCreateRequest,
              CarrierAccount = "b741b99f95e841639b54272834bc478c",
              ServicelevelToken = ServiceLevelUSPSEnum.UspsPriority.Value(),
          }
      )
  );
  ```
</CodeGroup>

The API will respond with the JSON serialized `Shipment` object. Shippo automatically creates the corresponding `rate` object, which you can use to retrieve the `amount` of the label.

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@shippo.com",
    "was_test": false,
    "rate": {
        "object_id": "cf6fea899f1848b494d9568e8266e076",
        "amount": "5.50",
        "currency": "USD",
        "amount_local": "5.50",
        "currency_local": "USD",
        "provider": "USPS",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "usps_priority",
        "carrier_account": "078870331023437cb917f5187429b093",
    },
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "status": "UNKNOWN",
        "status_details": "",
        "status_date": "2013-12-28T12:04:04.214Z"
    },
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "eta": "2013-12-30T12:00:00.000Z",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "",
    "messages": []
}
```


# Testing the Shippo API
Source: https://docs.goshippo.com/guides/testing

Use Shippo test mode to try all API features, including label creation, without being charged.

To help you learn about all the features in the Shippo API, we have created a test mode.
You can use the test mode to try all Shippo features including purchasing a label, without any charge.

This is useful when learning about the Shippo API for the first time, integrating it into your project, and testing out new features.

## How to use the Shippo Test Mode

To use Shippo test mode, first generate a test key in [API configuration in the Shippo API portal](https://portal.goshippo.com/api-config/api).

<img alt="Screenshot of UI for generating Shippo API test key" />

Click **Create new test key** and copy the resulting key. It will begin with `shippo_test_`.

To use test mode, insert your Shippo API test key in place of `<API_TOKEN>` for **every** API call.

The example below creates a new address object.

<Info>
  **Note**

  When testing, we recommend you use real verifiable addresses. This helps avoid errors due to malformed addresses.
</Info>

<CodeGroup>
  ```shell title="cURL" theme={null}
   curl https://api.goshippo.com/addresses/ \
      -H "Authorization: ShippoToken <API_TOKEN>" \
      -d name="Shawn Ippotle" \
      -d company="Shippo" \
      -d street1="215 Clayton St." \
      -d street2="" \
      -d city="San Francisco" \
      -d state="CA" \
      -d zip=94117 \
      -d country="US" \
      -d phone="+1 555 341 9393" \
      -d email="shippotle@shippo.com"\
      -d is_residential=True\
      -d metadata="Customer ID 123456"
  ```

  ```Python title="Python" theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  shippo_sdk.addresses.create(
      components.AddressCreateRequest(
          name="Shawn Ippotle",
          company="Shippo",
          street1="215 Clayton St.",
          city="San Francisco",
          state="CA",
          zip="94117",
          country="US", # iso2 country code
          phone="+1 555 341 9393",
          email="shippotle@shippo.com"
      )
  )
  ```

  ```PHP title="PHP" theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_TOKEN>");

  // Create address object
  $fromAddress = Shippo_Address::create( array(
      "name" => "Shawn Ippotle",
      "company" => "Shippo",
      "street1" => "215 Clayton St.",
      "city" => "San Francisco",
      "state" => "CA",
      "zip" => "94117",
      "country" => "US",
      "phone" => "+1 555 341 9393",
      "email" => "shippotle@shippo.com" 
  ));
  ```

  ```typescript title="TypeScript" theme={null}
  // Create address object
  const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>'});
  const addressFrom = await shippo.addresses.create({
      name: "Shawn Ippotle",
      company: "Shippo",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US", // iso2 country code
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com",
  });
  ```

  ```Java title="Java" theme={null}
      // Java
  Shippo.setApiKey('<API_TOKEN>');

  HashMap<String, Object> addressMap = new HashMap<String, Object>();
  addressMap.put("name", "Mr. Hippo");
  addressMap.put("company", "Shippo");
  addressMap.put("street1", "215 Clayton St.");
  addressMap.put("city", "San Francisco");
  addressMap.put("state", "CA");
  addressMap.put("zip", "94117");
  addressMap.put("country", "US");
  addressMap.put("phone", "+1 555 341 9393");
  addressMap.put("email", "support@goshipppo.com");

  Address createAddress = Address.create(addressMap);
  ```

  ```cs title="C#" theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_TOKEN>");
  Address address = await sdk.Addresses.CreateAsync(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Company = "Shippo",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  ```
</CodeGroup>

To help you identify test calls, responses in test mode include the key-value pair:

```json theme={null}
"test": true
```

## Carriers in Test Mode

You can use test mode to generate sample shipping labels. These labels are watermarked with **SAMPLE - DO NOT MAIL**. You cannot use these labels for shipping.

<img alt="Sample shipping label" />

The easiest way to generate your first label is to use a rate generated by USPS. Some carriers require a different test account credential to show test rates and generate test labels. For more information about which carriers require a separate test account, see our [carrier capabilities page](/carriers/carrier-capabilities).

## Notes About Test Mode

### Test Labels

* You cannot use test labels to ship a parcel.
* Rates requested in test mode may differ from actual rates in live mode.
* Test mode generates tracking numbers, but does not update the tracking information.
* Test mode currently does not work with the batch label process and manifesting. We are actively working on supporting these features.

### Test Data

* Refund requests in test mode will always return a success response, but no invoice item will be generated.
* When using the test key, you will only be able to access test data, not live data such as carrier accounts, transactions, and rates.
* When using the live key, you will only be able to access live data, not test data.
  * Exception: If you have not upgraded your API and are continuing to use version 2014-02-11, your live key will remain unchanged and you will continue to see both test data and live data. This means that your Shipment object can return one of 3 different values for the variables test.
    * True – All Rates returned in Shipment were tests.
    * False – All Rates returned in Shipment were live.
    * None – Rates returned in Shipment were both tests and live.

### Testing Carrier Accounts

* User-owned carrier accounts (where you have plugged in your own carrier credentials) created with test keys will only be available in test mode. To create live labels, users will need to connect their carrier accounts again using their live keys. Similarly, carrier accounts created using the live keys will not work in test mode.
  * Shippo carrier accounts will not require this, the carrier account object\_ids will work for both test and live mode.
  * Exception: If you have not upgraded your API and are continuing to use version 2014-02-11, you will not need to create separate test and live carrier accounts to view test data and create test labels when in live mode.


# Welcome to the Shippo API
Source: https://docs.goshippo.com/index

Shippo is a multi-carrier shipping API for 40+ carriers: rates, labels, tracking, and address validation over REST, SDKs, or the hosted MCP server for AI agents.

<CardGroup>
  <Card title="Quickstart Guide" icon="rocket" href="/guides/api-quickstart" />

  <Card title="API Keys" icon="key" href="https://portal.goshippo.com/api-config/api" />

  <Card title="Postman Collection" icon="paper-plane" href="https://god.gw.postman.com/run-collection/22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D22332580-e3f0581d-41f8-4c5c-894e-d9e22a87f6a5%26entityType%3Dcollection%26workspaceId%3Da131fa9b-fc39-440e-93bb-2586e9e1eb93" />

  <Card title="Client Libraries (SDK)" icon="code" href="/guides/client-libraries" />

  <Card title="MCP Server" icon="sparkles" href="/guides/mcp-server" />

  <Card title="API Status" icon="signal" href="https://status.goshippo.com/" />

  <Card title="API Portal" icon="browser" href="https://portal.goshippo.com/" />

  <Card title="Release Notes" icon="scroll" href="/api-concepts/api-change-log" />

  <Card title="Support" icon="headset" href="https://support.goshippo.com/hc/en-us" />
</CardGroup>

## How it works

Shippo's API standardizes carrier processes and streamlines the complexities of shipping, so you can offer a best-in-class solution without the upkeep. Get set up quick and easy with a customized, single integration to 40+ carriers, with little maintenance required.

This diagram illustrates how you can use the Shippo API to add shipping into your own application.

<img alt="Shippo basic architecture" />

<img alt="Shippo basic architecture" />

[Logistics Providers](https://goshippo.com/case-studies/shipbob/), [E-commerce platforms](https://goshippo.com/case-studies/weebly/), [Marketplaces](https://goshippo.com/case-studies/mercari/), and [Retailers](https://goshippo.com/case-studies/vnyl/) use Shippo to power their shipping capability.


# International shipping
Source: https://docs.goshippo.com/international-shipping/international-shipping

Ship internationally with the Shippo API by creating customs declarations and items to clear customs for your packages.

You can easily handle foreign addresses and customs forms directly through the Shippo API when shipping internationally (this includes shipping to US Territories for USPS). We've created a guide to make sure your packages clear customs and arrive safely!

## Create the Sender & Recipient Address Objects and Parcel Object

As with every Shipment, you need to first create or retrieve your two Address (sender and recipient) and Parcel objects first. Check out our [address validation tutorial](/addresses/address-validation) on how you can validate global addresses.

The only special requirement in this case is that the phone number of the sender and recipient are required. Apart from that there's nothing special about them for international shipments.

## Create a Customs Declaration and Customs Items

You will need to create a customs declaration and specify the items that are inside your international shipment. This is to ensure that the country you import goods into accepts your package at the border. The USPS website has a great [Shipping Restrictions](https://www.usps.com/ship/shipping-restrictions.htm) page with some general no-goes, as well as a more detailed [Index of Countries and Localities.](http://pe.usps.com/text/Imm/immctry.htm)

## What information do I need to submit for a Customs Declaration?

You can find an overview of all available fields in our [Customs Declaration reference section](/api-reference/customs-declarations/list-all-customs-declarations). Most carriers require you to specify `certify`, `certify_signer`, `contents_type`, `eel_pfc` and `incoterm`. Although not all carriers require it, we also recommend submitting the `items` field -- this significantly reduces the risk of the package being stuck in customs.

There are many optional fields that can be filled out depending on who you're shipping with, so please do your research ahead of time to make sure that you have all the required fields covered.

## Create your Customs Declaration and Items inline

To create a customs declaration, send a POST request with the necessary information to the Customs Declarations endpoint. You can create your Customs Items within the `items` attribute. Alternatively, you can create customs items individually via the [Customs Items API endpoint](/api-reference/customs-items/list-all-customs-items).

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/customs/declarations/\
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -H "Content-Type: application/json"\
      -d '{
            "contents_type": "MERCHANDISE",
            "non_delivery_option": "RETURN",
            "certify": true,
            "certify_signer": "Simon Kreuz",
            "incoterm": "DDU",
            "items": [{
                      "description": "T-shirt",
                      "quantity": 20,
                      "net_weight": "5",
                      "mass_unit": "lb",
                      "value_amount": "200",
                      "value_currency": "USD",
                      "tariff_number": "",
                      "origin_country": "US"
              }]
      }'
  ```

  ```python Python theme={null}
  customs_item = components.CustomsItemCreateRequest(
      description="T-Shirt",
      quantity=20,
      net_weight="1",
      mass_unit=components.WeightUnitEnum.LB,
      value_amount="200",
      value_currency="USD",
      origin_country="US",
  )

  customs_declaration = shippo_sdk.customs_declarations.create(
      components.CustomsDeclarationCreateRequest(
          contents_type=components.CustomsDeclarationContentsTypeEnum.MERCHANDISE,
          contents_explanation='T-Shirt purchase',
          non_delivery_option=components.CustomsDeclarationNonDeliveryOptionEnum.RETURN,
          certify=True,
          certify_signer='Simon Kreuz',
          items=[customs_item]
      )
  )
  ```

  ```php PHP theme={null}
  $customs_item = array(
      'description'=> 'T-Shirt',
      'quantity'=> '20',
      'net_weight'=> '1',
      'mass_unit'=> 'lb',
      'value_amount'=> '200',
      'value_currency'=> 'USD',
      'origin_country'=> 'US');

  $customs_declaration = Shippo_CustomsDeclaration::create(
  array(
      'contents_type'=> 'MERCHANDISE',
      'contents_explanation'=> 'T-Shirt purchase',
      'non_delivery_option'=> 'RETURN',
      'certify'=> 'true',
      'certify_signer'=> 'Simon Kreuz',
      'items'=> array($customs_item)
  ));
  ```

  ```typescript TypeScript theme={null}
  const customsItem: CustomsItem = {
      description: "T-Shirt",
      quantity: 20,
      netWeight: "1",
      massUnit: WeightUnitEnum.Lb,
      valueAmount: "200",
      valueCurrency: "USD",
      originCountry: "US",
  };

  const customsDeclaration = await shippo.customsDeclarations.create({
      contentsType: CustomsDeclarationContentsTypeEnum.Merchandise,
      contentsExplanation: "T-Shirt purchase",
      nonDeliveryOption: CustomsDeclarationNonDeliveryOptionEnum.Return,
      certify: true,
      certifySigner: "Simon Kreuz",
      items: [customsItem],
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> customsItemMap = new HashMap<String, Object>();
  customsItemMap.put("description", "T-Shirt");
  customsItemMap.put("quantity", 20);
  customsItemMap.put("net_weight", "1");
  customsItemMap.put("mass_unit", "lb");
  customsItemMap.put("value_amount", "200");
  customsItemMap.put("value_currency", "USD");
  customsItemMap.put("origin_country", "US");

  HashMap<String, Object> customsDeclarationMap = new HashMap<String, Object>();
  customsDeclarationMap.put("contents_type", "MERCHANDISE");
  customsDeclarationMap.put("contents_explanation", "T-Shirt purchase");
  customsDeclarationMap.put("non_delivery_option", "RETURN");
  customsDeclarationMap.put("certify", true);
  customsDeclarationMap.put("certify_signer", "Simon Kreuz");
  customsDeclarationMap.put("items", customsItemMap);

  CustomsDeclaration.create(customsDeclarationMap);
  ```

  ```csharp C# theme={null}
  CustomsItemCreateRequest customsItemCreateRequest = new CustomsItemCreateRequest()
  {
      Description = "T-Shirt",
      Quantity = 20,
      NetWeight = "1",
      MassUnit = WeightUnitEnum.Lb,
      ValueAmount = "200",
      ValueCurrency = "USD",
      OriginCountry = "US",
  };
  CustomsDeclaration customsDeclaration = await sdk.CustomsDeclarations.CreateAsync(
      new CustomsDeclarationCreateRequest()
      {
          ContentsType = CustomsDeclarationContentsTypeEnum.Merchandise,
          ContentsExplanation = "T-Shirt purchase",
          NonDeliveryOption = CustomsDeclarationNonDeliveryOptionEnum.Return,
          Certify = true,
          CertifySigner = "Simon Kreuz",
          Items = new List<CustomsItemCreateRequest>() { customsItemCreateRequest },
      }
  );
  ```
</CodeGroup>

## Create the Shipment, Get Rates, and Purchase Label

The only difference between this Shipment request and a domestic Shipment request is that you must include customs declaration in the Shipment API call. After that, you can retrieve Rates and create labels [just like for domestic shipments.](/guides/generate-shipping-label)

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -d address_from="d799c2679e644279b59fe661ac8fa488"\
      -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
      -d parcels="7df2ecf8b4224763ab7c71fae7ec8274"\
      -d customs_declaration="b741b99f95e841639b54272834bc478c"\
      -d async=false
  ```

  ```python Python theme={null}
  # Create shipment object
  shipment = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from="d799c2679e644279b59fe661ac8fa488",
          address_to="42236bcf36214f62bcc6d7f12f02a849",
          parcels=["7df2ecf8b4224763ab7c71fae7ec8274"],
          customs_declaration="b741b99f95e841639b54272834bc478c",
          async_=False
      )
  )
  ```

  ```php PHP theme={null}
  // Create shipment object
  $shipment = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "parcels" => array($parcel),
          "customs_declaration" => $customs_declaration -> object_id,
          "async" => False
      )
  );
  ```

  ```typescript TypeScript theme={null}
  // Create shipment object
  const shipment = await shippo.shipments.create({
      addressFrom: "d799c2679e644279b59fe661ac8fa488",
      addressTo: "42236bcf36214f62bcc6d7f12f02a849",
      parcels: ["7df2ecf8b4224763ab7c71fae7ec8274"],
      customsDeclaration: "b741b99f95e841639b54272834bc478c",
      async: false
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> createShipmentMap = new HashMap<String, Object>();
  createShipmentMap.put("address_to", addressToMap);
  createShipmentMap.put("address_from", addressFromMap);
  createShipmentMap.put("parcels", parcelMap);
  createShipmentMap.put("customs_declaration", customsDeclarationMap);
  createShipmentMap.put("async", false);

  Shipment.create(createShipmentMap);
  ```

  ```csharp C# theme={null}
  Shipment shipment = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = AddressFrom.CreateStr("d799c2679e644279b59fe661ac8fa488"),
          AddressTo = AddressTo.CreateStr("42236bcf36214f62bcc6d7f12f02a849"),
          Parcels = new List<Shippo.Models.Components.Parcels>()
          {
              Shippo.Models.Components.Parcels.CreateStr("7df2ecf8b4224763ab7c71fae7ec8274")
          },
          CustomsDeclaration = ShipmentCreateRequestCustomsDeclaration.CreateStr("b741b99f95e841639b54272834bc478c"),
          Async = false,
      }
  );
  ```
</CodeGroup>

You will get a response with a `rates` attribute. The `rates` usually contains multiple rates -- use your own business logic to filter out the rate you want to use and grab the corresponding Rate's object\_id.

```json theme={null}
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@shippo.com",
   "status":"SUCCESS",
   "address_from": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "address_to": {
        "object_id": "4c7185d353764d0985a6a7825aed8ffb",
        "validation_results": {},
        "is_complete": true,
        "name":"Mrs. Hippo",
        "street1":"200 University Ave W",
        "city":"Waterloo",
        "state":"ON",
        "zip":"N2L 3G1",
        "country":"CA",
        "phone":"+1 555 341 9393",
        "email":"support@shippo.com",
        "is_residential": false
    },
   "address_return":null,
   "parcels": [{
        "object_id": "ec952343dd4843c39b42aca620471fd5",
        "object_created": "2013-12-01T06:24:21.121Z",
        "object_updated": "2013-12-01T06:24:21.121Z",
        "object_owner": "shippotle@shippo.com",
        "template": null,
        "length":"5",
        "width":"5",
        "height":"5",
        "distance_unit":"in",
        "weight":"2",
        "mass_unit":"lb",
        "value_amount": null,
        "value_currency": null,
        "metadata": "",
        "line_items": [],
        "test": true
    }],
   "shipment_date":"2013-12-03T12:00:00Z",
   "extra":{
      "insurance": {
         "currency": "",
         "amount": "",
      },
      "reference_1": "",
      "reference_2": ""
   },
   "customs_declaration":"b741b99f95e841639b54272834bc478c",
   "rates": [
        {
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@shippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
               "name": "Priority Mail",
               "token": "usps_priority",
               "terms": ""
            },
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false,
            "zone": 1
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[],
   "metadata":"Customer ID 123456"
}
```

POST to the Transaction endpoint with your Rate object\_id to purchase your international shipping label.

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/transactions\
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -d rate="cf6fea899f1848b494d9568e8266e076"
      -d label_file_type="PDF"
      -d async=false
  ```

  ```python Python theme={null}
  # Get the first rate in the rates results.
  # Customize this based on your business logic.
  rate = shipment.rates[0]

  # Purchase the desired rate.
  transaction = api.transactions.create(
      components.TransactionCreateRequest(
          rate=rate.object_id,
          label_file_type=components.LabelFileTypeEnum.PDF,
          async_=False
      )
  )

  # Retrieve label url and tracking number or error message
  if transaction.status == components.TransactionStatusEnum.SUCCESS:
      print(transaction.label_url)
      print(transaction.tracking_number)
  else:
      print(transaction.messages)
  ```

  ```php PHP theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  $rate = $shipment["rates"][0];

  // Purchase the desired rate.
  $transaction = Shippo_Transaction::create( array( 
      'rate' => $rate["object_id"], 
      'label_file_type' => "PDF", 
      'async' => false ) );

  // Retrieve label url and tracking number or error message
  if ($transaction["status"] == "SUCCESS"){
      echo( $transaction["label_url"] );
      echo("\n");
      echo( $transaction["tracking_number"] );
  }else {
      echo( $transaction["messages"] );
  }
  ```

  ```typescript TypeScript theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  const rate = shipment.rates[0];

  // Purchase the desired rate.
  const transaction = await shippo.transactions.create({
      rate: rate.objectId,
      labelFileType: LabelFileTypeEnum.Pdf,
      async: false
  });
  ```

  ```java Java theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your own business logic
  Rate rate = rates.get(0);

  Map<String, Object> transactionParameters = new HashMap<String, Object>();
  transactionParameters.put("rate", rate.getObjectId());
  transactionParameters.put("async", false);
  Transaction transaction = Transaction.create(transactionParameters);

  if (transaction.getStatus().equals("SUCCESS")) {
      System.out.println(String.format("Label url : %s", transaction.getLabelUrl()));
      System.out.println(String.format("Tracking number : %s", transaction.getTrackingNumber()));
  } else {
      System.out.println(String.format("An Error has occured while generating you label. Messages : %s", transaction.getMessages()));
  }
  ```

  ```csharp C# theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your own business logic.
  Rate rate = shipment.Rates[0];
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateTransactionCreateRequest(
          new TransactionCreateRequest()
          {
              Rate = rate.ObjectId,
              LabelFileType = LabelFileTypeEnum.Pdf,
              Async = false,
          }
      )
  );
  if (transaction.Status == TransactionStatusEnum.Success)
  {
      Console.WriteLine($"{transaction.LabelUrl}");
      Console.WriteLine($"{transaction.TrackingNumber}");
  }
  else
  {
      Console.WriteLine($"{transaction.Messages}");
  }
  ```
</CodeGroup>

You will receive a JSON serialized Transaction object with your label, commercial invoice, and tracking information.

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@shippo.com",
    "was_test": false,
    "rate": {
        "object_id": "cf6fea899f1848b494d9568e8266e076",
        "amount": "5.50",
        "currency": "USD",
        "amount_local": "5.50",
        "currency_local": "USD",
        "provider": "USPS",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "usps_priority",
        "carrier_account": "078870331023437cb917f5187429b093",
    },
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "status": "UNKNOWN",
        "status_details": "",
        "status_date": "2013-12-28T12:04:04.214Z"
    },
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "eta": "2013-12-30T12:00:00.000Z",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "",
    "messages": []
}
```

### What about commercial invoices?

Most international shipments require you to add 3 commercial invoices in the package's "pouch", a special envelope attached on the package. Shippo automatically creates these 3 copies for you, which will be returned in the Transaction's `commercial_invoice` field.

## Country-specific shipping guidelines

### Shipping to Switzerland (CH)

* If shipping large value or large volume to Switzerland (greater than CHF 100,000 annual sales), you must register for Swiss VAT and pass that VAT number in your customs declaration `shipment.customs_declaration.exporter_identification.tax_id`.

### Shipping using APG

* If shipping to AU or NZ using APG, you must pass an ARN on the tax identifiers using `exporter_identification.tax_id` in your customs declaration.
* If shipping to an EU country using APG, you must pass an `IOSS` value on the tax identifiers using `Exporter_identification.tax_id` in your customs declaration.


# Manifests and SCAN forms
Source: https://docs.goshippo.com/manifests-and-pickups/manifest-and-scan-forms

Create manifests and SCAN forms to close out daily shipments so carriers can accept all packages with a single scan.

A manifest is a single-page document with a barcode that carriers can scan to accept all packages into transit without the need to scan each item individually, speeding up the package acceptance process. Manifests are close-outs of shipping labels of a certain day. Daily manifests are required by some carriers and are meant to be used for proper billing and acceptance of shipments. You can create Manifests with the Shippo SCAN Form and Manifest API.

## Create a new manifest

To create a manifest for your shipments, POST to the [Manifest endpoint](/api-reference/manifests/list-all-manifests) with an array of the `Transaction` object IDs you are looking to create the Manifest for, along with your `carrier_account` , `shipment_date` , and `address_from` (required for USPS).

Each transaction in your manifest must share the same `address_from`, `shipment_date`, and `carrier_account`.

<Info>
  **NOTE**

  The date format you use for `shipment_date` must be in the format 2014-01-18T00:35:03.463Z (ISO 8601 date). See the [create manifest](/api-reference/manifests/create-a-new-manifest) endpoint for an example.
</Info>

<CodeGroup>
  ```shell cURL theme={null}
  curl https://api.goshippo.com/manifests/
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -H "Content-Type: application/json"\
      -d '{
            "carrier_account": "b741b99f95e841639b54272834bc478c",
            "shipment_date": "2014-05-16T23:59:59Z",
            "address_from": "28828839a2b04e208ac2aa4945fbca9a",
            "transactions": [
              "64bba01845ef40d29374032599f22588",
              "c169aa586a844cc49da00d0272b590e1"
              ],
            "async": true
          }'
  ```

  ```python Python theme={null}
  manifest = shippo_sdk.manifests.create(
      components.ManifestCreateRequest(
          carrier_account="b741b99f95e841639b54272834bc478c",
          address_from="28828839a2b04e208ac2aa4945fbca9a",
          shipment_date="2014-05-16T23:59:59Z",
          transactions=["64bba01845ef40d29374032599f22588", "c169aa586a844cc49da00d0272b590e1"]
      )
  )
  ```

  ```php PHP theme={null}
  $manifest = Shippo_Manifest::create(
      array(
          'carrier_account'=> 'b741b99f95e841639b54272834bc478c',
          'shipment_date'=> '2014-05-16T23:59:59Z',
          'transactions'=> array('64bba01845ef40d29374032599f22588', 'c169aa586a844cc49da00d0272b590e1')
  ));
  ```

  ```typescript TypeScript theme={null}
  const manifest = await shippo.manifests.create({
      carrierAccount: "b741b99f95e841639b54272834bc478c",
      addressFrom: "28828839a2b04e208ac2aa4945fbca9a",
      shipmentDate: "2014-05-16T23:59:59Z",
      transactions: [
          "64bba01845ef40d29374032599f22588",
          "c169aa586a844cc49da00d0272b590e1"
      ]
  });
  ```

  ```java Java theme={null}
  HashMap<String, Object> manifestMap = new HashMap<String, Object>();
  manifestMap.put("carrier_account", "b741b99f95e841639b54272834bc478c");
  manifestMap.put("shipment_date", "2014-05-16T23:59:59Z");

  String[] transactionIds = {"64bba01845ef40d29374032599f22588",
                             "c169aa586a844cc49da00d0272b590e1"};
  manifestMap.put("transactions", transactions);

  Manifest.create(manifestMap);
  ```

  ```csharp C# theme={null}
  Manifest manifest = await sdk.Manifests.CreateAsync(
      new ManifestCreateRequest()
      {
          CarrierAccount = "b741b99f95e841639b54272834bc478c",
          AddressFrom = ManifestCreateRequestAddressFrom.CreateStr("28828839a2b04e208ac2aa4945fbca9a"),
          ShipmentDate = "2014-05-16T23:59:59Z",
          Transactions = new List<string> {
              "64bba01845ef40d29374032599f22588",
              "c169aa586a844cc49da00d0272b590e1",
          },
      }
  );
  ```
</CodeGroup>

<Info>
  **note**

  The manifest endpoint in the Shippo API supports both methods for specifying the `address_from` parameter using an object ID or setting the address parameters directly in the call.

  ```shell theme={null}
  curl https://api.goshippo.com/manifests/
      -H "Authorization: ShippoToken <API_TOKEN>"\
      -H "Content-Type: application/json"\
      -d '{
            "carrier_account": "b741b99f95e841639b54272834bc478c",
            "shipment_date": "2014-05-16T23:59:59Z",
            "address_from": {
  			"name": "Mr Shippo",
  			"street1": "765 W Adams St",
  			"street2": "",
  			"city": "Chicago",
  			"state": "IL",
  			"zip": "60661",
  			"country": "US",
  			"phone": "123454656677",
  			"email": "mrshippo@shippo.com"
              },
            "transactions": [
              "64bba01845ef40d29374032599f22588",
              "c169aa586a844cc49da00d0272b590e1"
              ],
            "async": true
          }'
  ```
</Info>

Manifesting an asynchronous process. Depending on the number of transactions you have included in your manifest, it may take a couple of minutes to generate a manifest.

While the Shippo API is generating your manifest, the `status` attribute in your response will be `QUEUED`.

```json theme={null}
"status": "QUEUED"
```

You can poll the status of the manifest by [retrieving the manifest](/api-reference/manifests/retrieve-a-manifest) using the manifest object ID. You can poll the status of the manifest by [retrieving the manifest](/api-reference/manifests/retrieve-a-manifest) using the manifest object ID. Review the [polling logic](#manifest-polling-logic) section for a suggested polling method.

```shell cURL theme={null}
curl https://api.goshippo.com/manifests/0fadebf6f60c4aca95fa01bcc59c79ae \
-H "Authorization: ShippoToken <API_TOKEN>"
```

If the `status` attribute in your response is `ERROR`, use our [manifest errors](/api-reference/manifests/list-all-manifests) list to help you debug your issue.

```json theme={null}
"status": "ERROR"
```

If the `status` attribute in your response is `SUCCESS`, in your response, you will find an array of links to your manifests in the `documents` attribute. Depending on how many shipments you've manifested, you may generate multiple files.

```json theme={null}
"status": "SUCCESS"
```

Manifests are always generated in PDFs. For the USPS, one manifest (SCAN Form) can contain up to 500 shipment information, so if you've manifested more than 500 shipments you will receive multiple PDFs.

```json theme={null}
{
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "carrier_account": "b741b99f95e841639b54272834bc478c",
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ],
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "mrhippo@shippo.com",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "shipment_date": "2014-05-16T23:59:59Z",
    "status": "SUCCESS",
    "transactions": [
        "64bba01845ef40d29374032599f22588",
        "c169aa586a844cc49da00d0272b590e1"
    ]
}
```

<Info>
  **NOTE**

  You can create more than one manifest for a single location, but you cannot add the same label to more than one manifest.
</Info>

### Manifest polling logic

We recommend adopting a polling logic similar to the following. Depending on your application, you may need to alter the wait times between polling.
IN polling requests, we reccomend

1. Create your manifest.
2. Wait for 3 seconds.
3. Retrieve manifest status.
4. If `"status": "SUCCESS"`, stop polling. If `"status": "QUEUED"` wait 10 seconds.
5. Retrieve manifest status.
6. If `"status": "SUCCESS"`, stop polling. If `"status": "QUEUED"` wait 30 seconds.
7. Retrieve manifest status.
8. If `"status": "SUCCESS"`, stop polling. If `"status": "QUEUED"` wait 1 minute.
9. Retrieve manifest status.
10. If `"status": "SUCCESS"`, stop polling. If `"status": "QUEUED"` wait 5 minutes.
11. And so on until `"status": "SUCCESS"`.

<Info>
  **Note**

  We have verified this polling sequence for a number of carriers including DHL eCommerce. For a best experience, we recommend implementing the entire sequence.
</Info>

## Which carriers require a manifest?

Most carriers, including FedEx, UPS and DHL Express, don't require you to create a manifest. As a certified carrier partner, Shippo automatically manifests packages for you if the carrier supports it. Your labels are pre-scanned and drivers are not required to scan each package individually on pickup.

### USPS (optional)

The USPS manifest is also known as "SCAN Form". A SCAN form is a PDF with a single barcode containing information about all your packages, so that the USPS doesn't need to scan each of your packages individually and all tracking codes are updated immediately.

### Canada Post (contract customers only)

If you have a Contract Account with Canada Post and are shipping more than 50 shipments a day you need to create a manifests to transmit the shipments for billing.

Customers that ship less than 50 daily can usually skip the manifest requirement, but are encouraged to verify with Canada Post.

### Australia Post

All Australia Post customers are required to manifest their shipments on a daily basis.

### DHL eCommerce

All DHL eCommerce customers are required to manifest their shipments on a daily basis.

### Purolator

Manifest capabilities are available for Purolator. It is not required by Purolator, however encouraged for record-keeping purposes.


# Pickups
Source: https://docs.goshippo.com/manifests-and-pickups/pickups

Schedule carrier pickups with USPS and DHL Express for your Shippo shipments using the pickups endpoint.

Shippo's pickups endpoint allows you to schedule pickups with USPS and DHL Express for eligible shipments that you have already created.

## Creating a pickup

You can create a pickup request by sending a POST request to the pickups endpoint. A pickup typically consists of the following parameters:

* `carrier_account`: The object ID of your USPS or DHL Express carrier account -- this is a mandatory field. You can retrieve this from your Rate requests or our  /carrier\_accounts endpoint.
* `location`: The following fields may also be included in location
  * `building_location_type:` where your parcels will be available for pickup (accepted enums are: Front Door, Back Door, Side Door, Knock on Door/Ring Bell, Mail Room, Office, Reception, In/At Mailbox, Security Deck, Shipping Dock, Other)
  * `building_type`: an optional field to describe the type of building (accepted enums are: apartment, building, department, floor, room, suite) where the pickup is located
  * `instructions`: pickup instructions for the courier (string). This is a mandatory field if the building\_location\_type is "Other"
  * `address`: the pickup address, which includes your name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters (/, &, \*, etc.) should not be included in any address element, especially name, company, and email.
* `transactions`: The transaction object ID(s) for the parcel(s) that need to be picked up. This should include all eligible parcels.
* `requested_start_time`: The earliest that your parcels will be ready for pickup (UTC time)
* `requested_end_time`: The latest that your parcels will be available for pickup (UTC time)
* `metadata`: an optional field for any additional information you might want to add such as the date of fulfillment

```json theme={null}
{
    "carrier_account":"6c51273296864869829b96a80fb13ea1",
    "location":{
            "building_location_type": "Other",
            "building_type": "apartment",
            "instructions": "Behind screen door",
            "address": {
                    "name": "Mrs Hippo",
                    "company": "Hungry Hippos",
                    "street1": "965 Mission St #201",
                    "city": "San Francisco",
                    "state": "CA",
                    "zip": "95122",
                    "country": "US",
                    "phone": "+14159876543",
                    "email": "mrshippo@shippo.com"
                }
    },
    "transactions": ["7439c279b374494c9a80ca24f59e6fc5"],
   "requested_start_time":"2019-02-18T12:00:00Z",
   "requested_end_time": "2019-02-18T16:00:00Z",
    "metadata": "Customer ID 123456",
    "is_test": false

}
```

The API will respond with the JSON serialized pickups object:

```json theme={null}
{
    "object_created": "2020-05-08T17:09:48.028Z",
    "object_updated": "2020-05-08T17:09:48.884Z",
    "object_id": "e0cefba8a75f401e893db1eb09075efb",
    "carrier_account": "6c51273296864869829b96a80fb13ea1",
    "location": {
        "instructions": "",
        "building_location_type": "Knock on door",
        "building_type": null,
        "address": {
            "object_id": "50ed4a6f0b0d4635b05315c79529798g",
            "name": "Mrs Hippo",
            "company": "Hungry Hippos",
            "street1": "965 Mission St #201",
            "street2": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "+14159876543",
            "email": "mrshippo@shippo.com"
        }
    },
    "transactions": [
        "e2aacd6211d347ada7b3d832f87db89h"
    ],
    "requested_start_time": "2020-05-12T19:00:00Z",
    "requested_end_time": "2020-05-12T23:00:00Z",
    "confirmed_start_time": "2020-05-09T12:00:00Z",
    "confirmed_end_time": "2020-05-09T23:59:59.999Z",
    "cancel_by_time": "2020-05-09T08:00:00Z",
    "status": "CONFIRMED",
    "confirmation_code": "WTC310058750",
    "timezone": "US/Pacific",
    "messages": null,
    "metadata": "Customer ID 123456",
    "is_test": false
}
```

Note that your confirmed pickup window will be in the time zone specified in the response, not UTC.

Make sure to take down your `confirmation_code` in the event you need to make changes. USPS may send you a follow-up email with your pickup confirmation code. To edit or cancel a pickup, you will need to contact USPS or DHL Express directly and provide your `confirmation_code`. The ability to edit or cancel a pickup through Shippo may be released in future iterations.

## Error messages

You may receive the following error messages if you are missing anything from the above fields in your request.

### Address or Address Elements Missing

Your pickup address must be submitted in the request with all elements, including city, zip code, country, and phone number.

```json theme={null}
{
    "address": [
        "This field is required."
    ]
}
```

### Special Characters Used

Special characters, including /, &, \*, and others, should not be used within the `address` elements, especially `name`, `company`, and `email`, as some of our carriers do not accept special characters.

```json theme={null}
{
    "messages": [
        "The company name of the pickup address is invalid or missing. Please update the company on the pickup address."
    ]
}
```

### No Eligible Parcels Available for Pickup

At least one eligible USPS or DHL Express transaction object ID must be included in the pickup request. For USPS, only Priority Mail Express, Priority Mail, international, or return service parcels are eligible for a scheduled pickup via API.

```json theme={null}
{
    "messages": [
        "A USPS pickup requires at least one transaction of the following service: Priority Mail Express, Priority Mail, any international service, or any return service. Please update the transactions."
    ],
}
```

### Pickup Already Scheduled for the Given Date and Time (USPS only)

USPS only allows one pickup scheduling request per day. If you have already scheduled a pickup for the given day, you will not be able to request another pickup.

```json theme={null}
{
    "messages": [
        "You have already requested a USPS pickup for today. Please leave any additional USPS packages at your designated pickup location and the carrier will collect them along with your already-scheduled package."
    ],
}
```


# OAuth
Source: https://docs.goshippo.com/o-auth-integrations/o-auth

Set up OAuth to let your platform users create or connect Shippo accounts and authorize your app to ship on their behalf.

To get started, please contact our [sales team](https://goshippo.com/become-a-shippo-partner) with the following information.

* **Company's Name:** This is presented to the user during the OAuth flow when they connect their Shippo account to your platform
* **Callback URL:** The URL vendors are redirected to after they connect their Shippo account. This is your site URL followed by /shippo-oauth-redirect/
* **Contact Email:** Your email address
* Brief description of use case

Here's a template you can copy and paste to quickly draft the message for our team.
You can paste this information in the `Additional Details:` section.

```
Hi,

I need OAuth credentials for my platform. I've included all requisite information below.

-   Company Name:
-   Callback URL:
-   Contact Email:
-   Use Case Description:

Please let me know if you have any questions.

Thanks,

<Your Name>
```

As a platform, implementing standalone accounts via OAuth is the best option to integrate Shippo if you want to offer shipping features within your platform, but don't want to handle all the billing or communication administration.

You can build all the required shipping features into your platform as normal. Then, your users can sign up for their own Shippo account via our OAuth flow and use their own API tokens to authenticate all shipping requests.

## The OAuth connection flow

The following process applies for setting up a Shippo account for a user on your platform:

* [Step 1](#step-1-link-to-the-shippo-oauth-flow): Starting on your site, the users clicks a link or button that takes them to the Shippo OAuth flow. The user is prompted to login or register for a Shippo account and, if missing, enter billing information (e.g. credit card). Finally, the user grants your platform permission to access their Shippo account.
* [Step 2](#step-2-redirect-to-your-site): The user is then redirected back to your site, passing along either an authorization code or an error in case the user chose not to complete the OAuth flow.
* [Step 3](#step-3-fetching-user-credentials-via-token-exchange): You need to make a request to our OAuth token endpoint to fetch the user's account ID and store it on your platform.

After all steps have been completed, your platform can make API requests on behalf of your users using their [authentication credentials](/o-auth-integrations/o-auth#authentication).

## Step 1: Link to the Shippo OAuth flow

To initiate the OAuth flow, your platform needs to link to the following URL:

```
https://goshippo.com/oauth/authorize?response_type=code&client_id=YOUR_PARTNER_ID&scope=*&state=YOUR_RANDOM_STRING
```

The endpoint accepts the following query parameters:

* `response_type`: "code"
* `client_id`: your unique partner ID (provided to you by Shippo)
* `scope`: "\*" (currently this is the only supported scope, allowing you full Shippo API access)
* `state`: a random string generated by your application, which you'll verify later to prevent CSRF attacks
* `utm_source`: an ID for your application (provided to you by Shippo)

After the user clicks on the link in your application, they'll be taken to Shippo's website to complete the OAuth process.

Unlike most OAuth implementations (like "Facebook Connect" or "Sign In with Twitter"), we've seamlessly added the process of creating a Shippo account right into our authorization flow. You don't have to worry about whether or not your users already have accounts!

The user has to complete the following steps on the Shippo OAuth flow:

1. Register a new Shippo account or login with an existing account.
2. If missing, enter billing information (e.g. credit card) to enable their Shippo account for production label purchase and other paid Shippo features.
3. Grant your platform permission to access their account.

The process looks as follows:

![oauth UI example](https://shippo-static.s3.amazonaws.com/img/various/oauth.gif)

## Step 2: Redirect to your site

After the user completed the OAuth flow, they are redirected back to your site's `redirect_uri`:

```
https://www.example-app.com/shippo-oauth-redirect?code=AUTH_CODE_HERE&state=my_random_string_def456
```

The request includes the following query parameters:

* `code`: the authorization code
* `state`: the random string you passed in step 1

You should first compare the `state` value to ensure it matches the one you started with in step 1. You can typically store the state value in a cookie or session, and compare it when the user comes back. This ensures your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.

If the authorization was denied by the user, they'll still be redirected back to your site, but the URL includes an error instead of the authorization code:

```
https://www.example-app.com/shippo-oauth-redirect?error=access_denied&error_description=The%20user%20denied%20your%20request&state=my_random_string_def456
```

## Step 3: Fetching user credentials via token exchange

In the last step you use the `code` from step 2 to fetch your user's access token, which you need for API authentication:

```shell theme={null}
curl https://goshippo.com/oauth/access_token\
    -d client_id=partner_abc123\
    -d client_secret=ef3034c9d025c62536e78ca0ccf9974cc2a75099\
    -d code=AUTH_CODE_HERE\
    -d grant_type=authorization_code\
    -X POST
```

The endpoint accepts the following parameters:

* `client_id`: your unique partner ID
* `client_secret`: your Shippo OAuth API secret key (different from your Shippo API key)
* `code`: the authorization code provided in step 2
* `grant_type`: "authorization\_code"

Shippo then returns the authentication credentials for the user:

```json theme={null}
{
    "access_token": "oauth.612BUDkTaTuJP3ll5-VkebURXUIJ5Zefxwda1tpd.U_akmGaXVQl80CWPXSbueSG7NX7sNe_HvLJLN1d1pn0=",
    "scope": "*",
    "token_type": "bearer"
}
```

The response contains the following parameters:

* `token_type`: "bearer"
* `scope`: "\*"
* `access_token`: the access you use to make API calls on behalf of your user. It never expires.

Please note that Shippo doesn't expire the `access_token`. It remains valid forever and you don't need to implement a refresh mechanism.

If the token exchange request fails, you get back an error response:

```json theme={null}
{
    "error": "invalid_grant",
    "error_description": "Invalid user credentials"
}
```

## Authentication

Once you have completed the OAuth flow for a user, you can make Shippo API requests on behalf of this user by authenticating via the normal `Authorization` header.

<Info>
  **Important Note**

  Use the Bearer `access_token` you generated in [Step 3](#step-3-fetching-user-credentials-via-token-exchange) to authenticate in the `Authorization` header.

  The format is `"Authorization: Bearer oauth.612BUDkTaTuJP3ll5-VkebURX"`, where  `oauth.612BUDkTaTuJP3ll5-VkebURX` is the generated `access_token`.

  This will not work if you use the format `"Authorization: ShippoToken"`.
</Info>

You need to set the header like this:

```shell theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: Bearer <OAUTH_BEARER_TOKEN>"\
    -H "Content-Type: application/json"\
    -d "{...}"
```

## Versioning

Since your users might independently upgrade the API version of their Shippo account, it's important that you explicitly set your API version in all of your API calls that you make on behalf of your users. You can set the API version in the header like this:

```shell theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: Bearer <OAUTH_BEARER_TOKEN>"\
    -H "Content-Type: application/json"\
    -H "Shippo-API-Version: 2018-02-08"\
    -d "{...}"
```

Please note that all API requests made on behalf of another Shippo user require API version 2018-02-08 or higher.

## OAuth Redirects

After your user has logged into their Shippo account, they are redirected back to your site. By default, you defined this redirect by the URL (Callback URL) you sent to our support team when setting up your OAuth.

During development and testing, it may be useful for you to be able to change your callback URL. For example, you may want to redirect to a development server while you build your integration. Depending on your development strategy, you might add redirects for development, test, production, or even localhost.

To control which redirect URL you use, include the query parameter `&redirect_uri` followed by the URL you want to redirect your user to after they have logged into their Shippo account.
If you do not specify a `&redirect_uri`, your default redirect URL is used.

<Info>
  **note**

  You must send all callback URLs you want to use to our partner support team in advance. You can do this when you first setup your [OAuth](/o-auth-integrations/o-auth) or can you can make a request afterwards. The feature described in this guide will not function until your callback URLs have been configured by our team. You can add as many as you need but you must specify which one is your default.
</Info>

The following example shows a redirect to the site `https://mysite.com/`. It's important to note the closing `/` on your URI is required.

```json theme={null}
https://goshippo.com/oauth/authorize?response_type=code&client_id=YOUR_PARTNER_ID&scope=*&state=YOUR_RANDOM_STRING&redirect_uri=https://mysite.com/
```


# Orders
Source: https://docs.goshippo.com/orders/orders

Create, retrieve, list, and manage orders via the Shippo API, then purchase labels and track shipments for each order.

The orders endpoint allows you to load orders from your system to the Shippo dashboard and to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order.

This tutorial will go through the following:

1. [Test mode:](#test-mode) how to test the orders endpoint
2. [Creating an order:](#creating-an-order) create orders programmatically via the API
3. [Retrieve an order:](#retrieve-an-order) get all details of an order by retrieving it
4. [List all orders:](#list-all-orders) list and filter your orders
5. [Purchase a label for an order:](#purchase-a-label-for-an-order) retrieve rates, create shipping labels, and track shipments for a given order
6. [Get a packing slip for an order:](#get-a-packing-slip-for-an-order) retrieve a PDF with all details of the order

## Test mode

There are a few things to be aware of when testing the Orders endpoint. For starters, you want to be sure that you're using your Shippo test token for authenticating your requests, to ensure that all orders are being created in test mode.

When you create a label using your Shippo test token and reference your order (see [Purchase a label for an order](#purchase-a-label-for-an-order)), it will transition the order's status for whatever the current status is to `"SHIPPED"`. This behavior maps to how it would work in live (either using the API *or* the Dashboard).

## Creating an Order

You can create an order with all the information about your order by sending a POST request to the orders endpoint. An order typically consists of the following information:

* `to_address`: this is a mandatory field, populated with the recipient address
* `from_address`: this is an optional field
* `line_items`: a line item represents the item that the buyer has purchased as part of this order. Line items are optional
* `shipping_` fields: these are optional parameters which describe the shipping rate that your customer chose during checkout. This is the information is displayed when you're using the Shippo dashboard to help select the right label for purchasing
* `order_number`: custom reference number for the order
* `order_status`: the current status of the order. You can find a [list of supported values](#order-status-values-order_status-field) below
* `placed_at`: the date and time when the order has been placed by the buyer. This is not the date and time that the order object has been created. This is a mandatory field

```shell cURL theme={null}
curl https://api.goshippo.com/orders/\
    -H "Authorization: ShippoToken <API_Token>"\
    -H "Content-Type: application/json"\
    -d '{
            "to_address": {
                "city": "San Francisco",
                "company": "Shippo",
                "country": "US",
                "email": "shippotle@shippo.com",
                "name": "Mr Hippo",
                "phone": "15553419393",
                "state": "CA",
                "street1": "215 Clayton St.",
                "zip": "94117"
            },
            "line_items": [
                {
                    "quantity": 1,
                    "sku": "HM-123",
                    "title": "Hippo Magazines",
                    "total_price": "12.10",
                    "currency": "USD",
                    "weight": "0.40",
                    "weight_unit": "lb"
                }
            ],
            "placed_at": "2016-09-23T01:28:12Z",
            "order_number": "#1068",
            "order_status": "PAID",
            "shipping_cost": "12.83",
            "shipping_cost_currency": "USD",
            "shipping_method": "USPS First Class Package",
            "subtotal_price": "12.10",
            "total_price": "24.93",
            "total_tax": "0.00",
            "currency": "USD",
            "weight": "0.40",
            "weight_unit": "lb"
        }'
```

The order object created on Shippo will look like the following:

```json theme={null}
{
    "currency": "USD",
    "from_address": null,
    "line_items": [
        {
            "currency": "USD",
            "description": null,
            "manufacture_country": null,
            "max_delivery_time": null,
            "max_ship_time": null,
            "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
            "quantity": 1,
            "sku": "HM-123",
            "title": "Hippo Magazines",
            "total_price": "12.10",
            "variant_title": "",
            "weight": "0.40",
            "weight_unit": "lb"
        }
    ],
    "notes": null,
    "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
    "object_owner": "shippotle@shippo.com",
    "order_number": "#1068",
    "order_status": "PAID",
    "placed_at": "2016-09-23T01:28:12Z",
    "shipping_cost": "12.83",
    "shipping_cost_currency": "USD",
    "shipping_method": "USPS First Class Package",
    "shop_app": "Shippo",
    "subtotal_price": "12.10",
    "to_address": {
        "city": "San Francisco",
        "company": "Shippo",
        "country": "US",
        "email": "shippotle@shippo.com",
        "is_complete": true,
        "is_residential": null,
        "metadata": "",
        "name": "Mr Hippo",
        "object_created": "2016-09-23T01:38:56Z",
        "object_id": "d799c2679e644279b59fe661ac8fa488",
        "object_owner": "shippotle@shippo.com",
        "object_updated": "2016-09-23T01:38:56Z",
        "phone": "15553419393",
        "state": "CA",
        "street1": "215 Clayton St.",
        "street2": "",
        "validation_results": [],
        "zip": "94117"
    },
    "total_price": "24.93",
    "total_tax": "0.00",
    "transactions": [],
    "weight": "0.40",
    "weight_unit": "lb"
}
```

## Retrieve an Order

You can retrieve an order by sending a GET request to the orders endpoint at `/orders/<order-object-id>`. You can retrieve any order created through the API, manually through the Shippo dashboard, or orders imported through one of our shopping cart integrations.

```shell cURL theme={null}
curl https://api.goshippo.com/orders/4f2bc588e4e5446cb3f9fdb7cd5e190b\
	-H "Authorization: ShippoToken <API_Token>"
```

The order object returned will be displayed like the sample order from above.

## List all Orders

You can list all orders created by sending a GET request to the orders endpoint. The result will be paginated.

```shell cURL theme={null}
curl https://api.goshippo.com/orders/\
    -H "Authorization: ShippoToken <API_Token>"
```

The request will return the paginated list like this:

```json theme={null}
{
    "count": 1382,
    "next": "https://api.goshippo.com/orders/?page=2",
    "previous": null,
    "results": [
        {
            "object_id": "4f2bc588e4e5446cb3f9fdb7cd5e190b",
            "object_owner": "shippotle@shippo.com",
            "order_number": "#1068",
            "order_status": "PAID",
            "placed_at": "2016-09-23T01:28:12Z",
            "to_address": {
                "object_created": "2016-09-23T01:38:56Z",
                "object_updated": "2016-09-23T01:38:56Z",
                "object_id": "d799c2679e644279b59fe661ac8fa488",
                "object_owner": "shippotle@shippo.com",
                "is_complete": true,
                "validation_results": {},
                "name": "Mr Hippo",
                "company": "Shippo",
                "street1": "215 Clayton St.",
                "street2": "",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94117",
                "country": "US",
                "phone": "15553419393",
                "email": "shippotle@shippo.com",
                "is_residential": null,
                "metadata": ""
            },
            "from_address": null,
            "line_items": [
                {
                    "object_id": "abf7d5675d744b6ea9fdb6f796b28f28",
                    "title": "Hippo Magazines",
                    "variant_title": "",
                    "sku": "HM-123",
                    "quantity": 1,
                    "total_price": "12.10",
                    "currency": "USD",
                    "weight": "0.40",
                    "weight_unit": "lb",
                    "manufacture_country": null,
                    "max_ship_time": null,
                    "max_delivery_time": null,
                    "description": null
                }
            ],
            "shipping_cost": "12.83",
            "shipping_cost_currency": "USD",
            "shipping_method": "USPS First Class Package",
            "shop_app": "Shippo",
            "subtotal_price": "12.10",
            "total_price": "24.93",
            "total_tax": "0.00",
            "currency": "USD",
            "transactions": [],
            "weight": "0.40",
            "weight_unit": "lb",
            "notes": null
        },
        ...
    ]
}
```

### Filter an Order list

You can also filter the order list with the following filters:

* `shop_app`: only return orders from a specific store platform. [See list of all shop\_app values below](#supported-platforms-shop_app-field)
* `start_date`: only return orders created after a specific date and time (ISO 8601 UTC format). This is based on the `placed_at` field, meaning when the order has been placed, not when the order object was created on the Shippo
* `end_date`: similar to the start\_date filter, only return orders before after a specific date and time
* `order_status`: only return orders with a status equal to the selected value. `order_status` is an array parameter that requires array notation. For example `orders/?order_status[]=PAID&order_status[]=UNKNOWN`.  [See list of all order\_status values below](#order-status-values-order_status-field)

The follow request, for instance, will return all Shopify orders placed after 2023/04/17 and before 2022/04/25 with a `PAID` status:

```shell cURL theme={null}
curl 'https://api.goshippo.com/orders?end_date=2023-04-25T23:59:59&page=1&results=25&shop_app=Shopify&start_date=2023-04-17T23:59:59&order_status[]=PAID&order_status[]=SHIPPED' \
  -H 'Authorization: ShippoToken <API_Token>'
```

## Purchase a label for an Order

When creating test labels for an order, the order status will be automatically changed from whatever status it had to `"SHIPPED"`.

There are two ways to create a shipping label for an order, outlined in the following tutorials:

* [First Shipment](/guides/generate-shipping-label): this tutorial will show you how to retrieve a list of rates first, then select a rate for purchasing
* [Single Call Label Creation](/guides/single-call): this tutorial will allow you to specify the exact carrier and service level for purchasing in one API call

When you create the Shipment, you can reference the order's to\_address object via it's `object_id`.

**Make sure to reference your order's object\_id in the `order` attribute of the transaction request so that the transaction is linked to your order.**

```shell cURL theme={null}
curl https://api.goshippo.com/transactions/\
    -H "Authorization: ShippoToken <API_Token>"\
    -H "Content-Type: application/json"\
    -d '{
        "shipment": {
            "address_from": {
                "name": "Mr. Hippo",
                "street1": "215 Clayton St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94117",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@shippo.com"
            },
            "address_to": "d799c2679e644279b59fe661ac8fa488",
            "parcels": [{
                "length": "5",
                "width": "5",
                "height": "5",
                "distance_unit": "in",
                "weight": "2",
                "mass_unit": "lb"
            }]
        },
        "carrier_account": "b741b99f95e841639b54272834bc478c",
        "servicelevel_token": "usps_first",
        "order": "4f2bc588e4e5446cb3f9fdb7cd5e190b"
        }'
```

The `object_id` and `label_url` of the newly created transaction object will be reflected in the `transactions` array of the orders object.

## Get a Packing Slip for an Order

A packing slip summarizes all relevant information of the order and is often used for picking and packing purposes.

You can GET a packing slip for any order via the `/orders/<order-object-id>/packingslip/` endpoint. The endpoint will return the link to the packing slip PDF. Shippo will automatically create one packing slip page per label you have created.

```shell theme={null}
curl https://api.goshippo.com/orders/4f2bc588e4e5446cb3f9fdb7cd5e190b/packingslip/\
    -H "Authorization: ShippoToken <API_Token>"
```

The request will return the packing slip link. The link expires after 24 hours.

```json theme={null}
{
    "created": "2017-10-11T17:55:39.172",
    "expires": "2017-10-12T17:55:39.172",
    "slip_url": "https://shippo-delivery-east.s3.amazonaws.com/packingslip_002c28cb4c5661526c8c05f3f336a5ab.pdf?Signature=Cwdox9AJ5BPdlDtVpGWHitROtj0%3D&Expires=1539280539&AWSAccessKeyId=AKIAJGLCC5MYLLWIG42A"
}
```

## Order status values (order\_status field)

The order field `order_status` indicates the current status of an order. Supported platforms include:

* UNKNOWN: fallback in case no other value is given
* AWAITPAY: awaiting payment by buyer
* PAID: paid by buyer
* REFUNDED: refunded payment to buyer
* CANCELLED: canceled by buyer
* PARTIALLY\_FULFILLED: some, but not all of the order items have been fulfilled
* SHIPPED: all order items have been shipped

The order status field is a Shippo controlled field, so it cannot be changed after you set its initial state in your POST request. When an label has been created for a specific order, the order's status will be automatically changed to `"SHIPPED"`.

## Supported platforms (shop\_app field)

The order field `shop_app` indicates which platform the order originated from. Supported platforms include:

* Amazon
* Bigcommerce
* CSV\_Import
* eBay
* Etsy
* GoDaddy
* Magento
* Shopify
* Spreecommerce
* StripeRelay
* Weebly
* WooCommerce
* Shippo (for orders created via the Shippo API or App)
* ePages


# Appendix
Source: https://docs.goshippo.com/partner-integration/appendix

Glossary of key Shippo integration concepts including address validation, rate shopping, label purchase, and tracking.

## Concepts and Terminology

Throughout this guide we will be using a number of terms that may not be familiar to you. We have provided a glossary of terms to help you understand the concepts and terminology used in this guide.

### Address Validation

Address validation is necessary to ensure items will be processed correctly by the carrier and not rejected, returned to sender, or cause excess postage fees upon delivery.

It is important to [validate](/addresses/address-validation) both the origin and destination addressed. The typical place for this to be done for optimal user experience for the merchants is to create their mailing address in a shipping administration section of the platform. Similarly for the buyers, it is best to validate addresses when they are filling out their shipping address. Otherwise, the merchant could experience a scenario where they attempt to print a label for an order, and the address validation fails at that point, preventing a label from being generated. This causes inefficiencies in the merchant workflow and can be easily avoided by validating the addresses well ahead of time.

### Rate Shopping

A partner can offer sellers an advantage in the market by providing more accurate shipping rates at the time of checkout.

Once an order has been created, merchants are going to want to choose a shipping service and carrier that meets their requirements for speed and cost. Rate shopping is the act of calling the Shippo [/shipments endpoint](/api-reference/shipments/list-all-shipments) and examining the object in the returned rates array. Each of these objects represents a unique carrier and service level combination and allows the merchant to select which of these options is optimal for an individual order. Once a rate has been selected that rate can be purchased using the [/transactions](/api-reference/transactions/list-all-shipping-labels) endpoint.

### Label Purchase

Once a merchant has made a decision on a rate, the next logical step is to print the label. The label is created by passing the rate's object\_id to the [/transactions endpoint](/api-reference/transactions/list-all-shipping-labels). A label URL will be returned in the transaction response which can be surfaced to the merchant for download.

An important thing to consider here is allowing your merchants full access to the available label formats. These are described in the API reference below for the [/transactions endpoint](/api-reference/transactions/list-all-shipping-labels), but partners will need a place for the user to configure their shipping settings.

Since label purchase is a call from the partner's platform to Shippo, and (usually) from Shippo to the chosen carrier who creates the label, there is a negligible latency in the creation of labels. As such, partners should consider using the `async:true` flag in the POST request to [/transactions](/api-reference/transactions/list-all-shipping-labels) wherever possible to prevent a block in the workflow. An asynchronous request is acknowledged immediately by Shippo and the transaction\_created webhook is triggered once the label has been generated by the carrier and passed to Shippo.

### Refund a label

Mistakes happen and sometimes you need to generate a new label for a shipment. The [/refunds](/api-reference/refunds/list-all-refunds) endpoint allows a merchant to have an "oops" button when they need one. This is typically added wherever a user would manage orders.

### Connect Carrier Accounts

As partners are looking to allow their users to add their own carrier accounts, you will need to implement this endpoint. There will need to be a form built for each carrier as they all require different information to connect an account to Shippo. Our documentation is exceptional on this, and for inspiration on building the carrier connection forms, we recommend you look at your version of the Shippo app to see how we configure the ability to add carrier accounts.

The most important part of this process is to capture the returned object\_id of the carrier account that has been created. That object id is specific to the merchant who has added their account into a partner's system and should be stored in your database where you can access it later for rate shopping for this merchant. Details of how to implement this are below in the /transaction endpoints section.

### Tracking Information

Tracking information can be conveyed in several ways depending on the partner's desire to build. We recommend using Shippo's API to create a post-purchase solution in the partner interface where your merchants and buyers can see the status of their orders in the same place the purchase was made. The reality is partners should control the tracking experience, and you don't want someone to buy on your platform without being able to know where the order is.

The simplest way is to pass the tracking information back to the merchant and consumer via the tracking\_label\_provider field returned in a [/transaction](/api-reference/transactions/list-all-shipping-labels) POST response. This field returns a URL to the carrier's tracking page for the tracking number on the label that was generated with the /transaction call.

The other common way to handle this is to use webhooks to subscribe to the track\_updated event. We will post updates on a shipment's tracking status to the endpoint you provide us in your webhook configuration (done inside the Shippo app). Documentation on webhooks can be found here.

### Returns

[Returning](/shipments/returns) an object is commonly done in two ways: either a return label is placed inside the box when a merchant ships an order, or a label is provided to the customer on demand. If the former option is desired, a scan-based return label is generated according to the guide here. Note, this is for a USPS scan based return label only, for the other carriers, returns should be handled by creating a standard (known as an outbound label) label with the addresses reversed from the initial merchant shipment. The rest of the information on the shipment can be considered to be the same, however.

### Manifests

[Manifests and USPS SCAN forms](/manifests-and-pickups/manifest-and-scan-forms) allow merchants to create a single piece of paper they can hand to the carrier at pickup time. The Manifest has a list of all the packages the carrier is going to be picking up that day and greatly speeds up the process of the carrier accepting each of the day's packages.

### Webhooks

[Webhooks](/tracking/webhooks) can be configured to deliver information on six different event types: all, transaction\_created, transaction\_updated, track\_updated, batch\_created, and batch\_purchased. The guide for working with webhooks can be found [here](/tracking/webhooks).

### Metadata

There is a metadata field on every resource that is part of the Shippo API. This field is limited to text data with a max length of 100 characters. It is useful for helping to cross-link objects like shipments, rates, and transactions to other associated data living in the user's adjacent systems. For example, an e-commerce platform user may want to tag the transaction object with the order number from their OMS. Or, a 3PL user may want to note which warehouse a shipment is associated with. There are an infinite number of possibilities here, and we encourage you to use this field for whatever you need it for!


# Business Cases for the Shippo API
Source: https://docs.goshippo.com/partner-integration/business-cases

Learn how platforms, 3PLs, single merchants, and returns providers integrate with the Shippo API for order fulfillment.

These are integration models that Shippo supports for different types of businesses. Please keep in mind that these are not the only business types that are supported but common uses.

## Platforms

E-commerce platforms commonly use Shippo to provide a native shipping solution that allows their merchants to purchase labels and track labels. Often a platform integration will include functionality to track packages for carriers Shippo supports but were not purchased on Shippo. A platform will often choose either a Gray or White label integration based on their business needs.

## Third Party Logistics

Third Party Logistics (3PL) companies leverage Shippo to manage and reconcile shipping for clients of various sizes and carrier relationship. By integrating with Shippo 3PL's gain the ability to use their own carrier relationships, shippers own accounts, and Shippo's.  They will typically build a white label solution leveraging the tennant account structure for the ability to separate out invoicing and carrier management.

## Single Merchant Implementation

Often larger merchants want to build shipping into an in house solution for managing, sales, inventory, or other aspects of their business. This will usually involve a single Shippo account using a white label account type. If there are multiple locations such as warehouses or stores it is likely the adding the tennant account structure will also make sense.

## Returns

Returns can be managed through Shippo by including a scan based outbound return label that is tied to an outbound label or generating a fresh label that returns merchandise to a seller. Scan based labels are used often for exchanges, trade-ins, or try before you buy use cases.

Shippo is also used to power returns portals allowing merchants to take advantage of carrier relationships from the portal, their own, or Shippo's accounts. This is typically a new label sent out for merchandise to be returned to the merchant, a distribution center, or reseller.


# Choosing Business Cases/User Stories
Source: https://docs.goshippo.com/partner-integration/choosing-business-cases

Select user stories for your Shippo integration covering shipments, customs, multi-parcel, refunds, and tracking scenarios.

To build the desired shipping system using Shippo's API, integrating partners will need to choose from a list of user stories. These user stories represent different business cases, which are the various scenarios that can occur when fulfilling orders. By selecting the appropriate user stories, the integrating partner will define the work that needs to be done to build the desired shipping system.

For example, the integrating partner may need to handle scenarios such as printing shipping labels, generating tracking numbers, processing returns, handling multiple carriers and shipping options, and integrating with customs clearance. By selecting the appropriate user stories, the integrating partner can ensure that the shipping system they build is customized to meet their specific business needs. Shippo's API offers a wide range of user stories to choose from, making it easy to build a flexible and customizable shipping system.

## User Stories to be Selected

### Shipments & Transactions

The following user stories cover the Shipments and Transactions endpoints using Shippo's API:

These user stories cover the functionalities that are associated with fetching carrier rates, rate shopping, and purchasing labels using Shippo's API. By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can compare rates and purchase labels seamlessly.

* As a Shipper, I want to compare rates and then purchase a label
* As a Shipper, I want to purchase a label in one step
* As a Shipper, I want to display rates to a consumer to choose a rate and then purchase a label
* As a Shipper, I want to be able to view the purchased label
* As a Shipper, I want to be able to print the purchased label
* As a Shipper, I want to be able to refund the purchased label

### Customs Declarations

Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your cross-border shipments. The following user stories cover customs declarations using Shippo's API:

* As a Shipper, I want to include customs data included in my shipment creation requests
* As a Shipper, I want to print commercial invoices to include with my cross-border packages

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can include customs data in shipment creation requests and properly document cross-border packages. This functionality is important for proper customs clearance and acceptance

### Multi-Parcel Shipments

Multi-parcel shipments are shipments with multiple packages sent to the same destination that can be grouped together in a multi-piece shipment to save money. The following user stories cover multi-parcel shipments:

* As a Shipper, I want to be able to create a multi-parcel shipment and receive shipping rates
* As a Shipper, I want to be able to purchase a label using the multi-parcel shipment's rates
* As a Shipper, I want to be able to view the purchased label
* As a Shipper, I want to be able to print the purchased label
* As a Shipper, I want to be able to refund the purchased labels

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create multi-parcel shipments, receive shipping rates, purchase labels, and view and print purchased labels. This functionality is important for shipments that require multiple packages sent to the same destination. For more information on multi-parcel shipments, please visit the following link: /shipments/multi-piece-shipment

### Refunding Labels

Refunding labels is an important process that allows shippers to return money spent on unused labels. However, there are certain best practices that should be followed when refunding labels, such as checking that a label has not been used before issuing a refund, pending refunds to ensure a label has not been printed and will be used, and blocking the reprinting of a refunded label. The following user stories cover label refunds:

* As a Shipper, I want to be able to check the status of a label before refunding
* As a Shipper, I want to be able to hold a refund request before distributing funds
* As a Shipper, I want to be able to block reprinting a label that has a refund request
* As a Shipper, I want to be able to check the status of a refund request

By selecting the appropriate user stories, integrating partners can ensure that they are able to properly manage refunds and avoid issues such as refunding a label that has already been used. For more information on label refunds, please visit the following link: /billing-and-invoices/refunding-labels

### Tracking Shipments

The Shippo Tracking API allows you to track shipments across all carriers with normalized data, full tracking history and real-time updates. When combined with webhooks, you will get push-style notifications anytime a tracking update occurs from the carrier. This powerful combination allows you to always know what the latest tracking information is across all of your shipments and if a recipient may need to take action to retrieve their shipment in a single service.

Associated user stories should include:

* As a (Shipper) I want to be able to receive automatic tracking updates on a shipment
* As a (Shipper) I want to be able to request the tracking status of a shipment
* As a (Shipper) I want to be able to get notifications when a shipment is delivered
* As a (Shipper) I want to be able to receive alerts for shipping exceptions

### Webhooks

Webhooks are a part of the Shippo integration that will allow you to receive automatic updates when subscribed events occur. Much like other webhooks, you will request subscription notifications are sent to specific endpoints. This is useful for sending shipping updates to consumers, monitoring for undeliverable packages, transaction administration, and many other use cases.

| Webhook             | Use                                                                                                                                                                                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transaction Created | Sent whenever a transaction is created in your account. The POST request body will contain a JSON of the Transaction object that was created.                                                                                                                                      |
| Transaction Updated | Sent whenever a transaction is updated in your account. The POST request body will contain a JSON of the Transaction object that was updated.                                                                                                                                      |
| Track Updated       | For tracking status updates. The POST request body will contain a JSON of the Tracking object. If you are interested in the types of events returned within the track\_updated field, please view more details [here](https://goshippo.com/docs/tracking#tracking-status-updates). |
| Batch Created       | For creating the Batch object that contain Batch Shipments. This process is done asynchronously, so first you'd get an empty Batch object back, then Batch Shipments will be created in the background.                                                                            |
| Batch Purchased     | For purchasing Batch Shipments through the Batch endpoint. This request is done asynchronously as well. Once purchases are complete, you will be able to download a merged PDF containing up to 100 labels per file.                                                               |

Associated user stories should include:

* As a (Shipper) I want to be able to subscribe to a webhook and specify the update
* As a (Shipper) I want to be able to unsubscribe from a webhook
* As a (Shipper) I want to be subscribed to a webhook automatically when \_\_\_ occurs

### Batch Shipments

Batch shipments allow the ability to create and purchase many shipments in one API call. The following user stories cover batch shipments using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create and purchase many shipments in one API call, which is useful for shippers that work in batches at the end of or several times a day. Batching is a flexible process that can purchase many shipments from different carriers or be used to purchase an array of shipments for a specified service level and carrier. For more information on batch shipments, please visit the following link: /shipments/batch-label-creation

* As a Shipper, I want to be able to purchase a batch
* As a Shipper, I want to be able to add a shipment to a batch
* As a Shipper, I want to be able to remove a shipment from a batch
* As a Shipper, I want to be able to get updated when an exception occurs
* As a Shipper, I want to be able to handle exceptions that occur during batch processing
* As a Shipper, I want to be able to notify specific recipients when a batch is purchased
* As a Shipper, I want to be able to retrieve the details of a batch

### Carrier Integration

The following user stories cover the integration of carriers using Shippo's API:

* As a Shipper, I want to be able to create a new carrier account that I will share with my merchants
* As a Shipper, I want to be able to create a new BYOA carrier
* As a Shipper, I want to be able to retrieve the details of an individual carrier account
* As a Shipper, I want to be able to update a BYOA carrier account
* As a Shipper, I want rates that are cost-effective for my business to deliver the sold product to the shipper on or before the date I told them at checkout
* As a Platform, I want to be able to list a merchant's carrier accounts
* As a Platform, I want to be able to add a carrier account to a merchant
* As a Platform, I want to be able to disable a merchant's carrier accounts
* As a Platform, I want to be able to remove a merchant's carrier account
* As a Platform, I want to be able to auto-provision a merchant's carrier account for carrier
* As a Platform, I want to be able to provide detailed billing information to my merchants

Note that the "list all carrier accounts" user story is not applicable for the platform, as the platform only has access to the carrier accounts of their merchants, not all carrier accounts.

### Carrier Manifests and Scan Forms

Carrier Manifests are close-outs of shipping labels of a certain day. Daily manifests are required by some carriers and are meant to be used for proper billing and acceptance of shipments. The following user stories cover Carrier Manifests and Scan Forms using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can create, retrieve, and list shipping manifests using Shippo's SCAN Form and Manifest API. This functionality is important for proper billing and acceptance of shipments with some carriers. For more information on Carrier Manifests and Scan Forms, please visit the following link: /manifests-and-pickups/manifest-and-scan-forms

* As a Shipper, I want to be able to create a shipping manifest
* As a Shipper, I want to be able to retrieve a shipping manifest
* As a Shipper, I want to be able to list all manifests

### Address Management

Shippo's API provides functionalities for validating and storing addresses, which can be useful for e-commerce integrations. The following user stories cover address management using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can validate and store addresses, which can prevent complications later in the checkout process. These functionalities can also provide value for use cases such as return and shipping addresses that do not change or a customer address book for recurring transactions.

* As a Shipper, I want to be able to validate and store an address at a specific point
* As a Shipper, I want to be able to decide what to do when an address fails validation
* As a Shipper, I want to be able to retrieve a stored address object ID for a specific use case
* As a Shipper, I want to be able to turn on and off the ability to bypass address validation
* As a Shipper, I want to be able to override failed address validation
* As a Shipper, I want to be able to update and store a new address with validation
* As a Shipper, I want to be able to update and store a new address without validation

### Parcel Templates

Parcel templates are predefined package parameters that can be used qto streamline the shipping process. The following user stories cover parcel templates using Shippo's API:

By selecting the appropriate user stories, integrating partners can ensure that their e-commerce platforms can use predefined package parameters to streamline the shipment process. These functionalities can be useful for situations where a merchant always ships a subscription in the same sized box, or a warehouse only uses a few box sizes, making rating and shipping easier. For more information on parcel templates, please visit the following link: /api-reference/user-parcel-templates

* As a Shipper, I want to be able to store a parcel template
* As a Shipper, I want to be able to delete a stored parcel template
* As a Shipper, I want to be able to update a stored parcel template
* As a Shipper, I want to be able to retrieve and apply a parcel template when needed
* As a Shipper, I want to be able to retrieve a list of parcel templates for my account

### Orders

The orders endpoint allows you to load orders from your system to the Shippo dashboard and to create, retrieve, list, and manage orders programmatically. You can also retrieve shipping rates, purchase labels, and track shipments for each order.

This functionality /o-auth-integrations/web-app-order-sync will only be needed if you are not building a native shipping user interface.
Associated user stories should include:

* As a (Shipper) I want to have my orders viewable in the Shippo dashboard
* As a (Shipper) I want to have my orders update when changes or canceled in the Shippo dashboard
* As a (Shipper) I want to have my shipping information viewable in my \_\_\_\_ dashboard

### Special Shipments

Special shipments can include a variety of situations like dry ice, alcohol, or lightly regulated hazardous materials. In general, you will use the user stories and API functions for other shipments when handling these use cases but need to include additional data based on the situation. Because these requirements can change based on carrier, location, and other factors, be sure to discuss your use cases for these situations with your Shippo team.

Associated user stories should include:

* As a (Shipper) I want to include needed data when creating a special shipment
* As a (Shipper) I want to update needed data when creating a special shipment

### Returns

Returns have a variety of use cases that the Shippo API can be used to address. To simplify the matter it is best to define what the types of returns are.
Scan Based Returns - These are return labels a shipper is not charged for unless it is used by the recipient to ship a package. The carriers require these labels be associated with an original outbound label and will bill for the size and weight of that package. A great use case for these labels is when a recipient is returning an item for a like item such as trading in a cell phone.
Shipper Provided Return Labels - These are labels that are generated by a business for a customer to return an item and not provided in the original packaging. From a technical perspective, these labels are the same as a regular outbound label. The business will most likely provide a PDF or the URL of the label for the customer to print out and return the item.
Stand Alone Return Labels - These are labels provided to a customer to return an item where no original label may have been purchased through Shippo. This may be situations like warranty claims, returns portals, collectible evaluation, and trade ins. From a technical perspective, these labels are the same as a regular outbound label. The business will most likely provide a PDF or the URL of the label for the customer to print out and return the item.

Associated user stories should include:

* As a (Shipper) I want to be able to include a scan based return label with an outbound shipment
* As a (Shipper) I want to be able to send a new outbound label to process a return
* As a (Shipper) I want to be able to send a return label to a (customer) related to an original Shippo label purchase

### Managing Payment Methods

Payment methods are typically a card or ACH data kept on file to collect payment for labels and label fees as well as refund labels. If you are building a native UI you will need to build a method for these updates. If you are using Shippos UI you will need to build a method to redirect users to the screens in Shippos UI to perform updates.

It is important to note there is not an API for managing payment methods at this time. White label integrations will manage payments through their Shippo account and Gray Label will require using OAuth to access the Shippo Web App.

Associated user stories should include:

* As a (Shipper) I want to add a new payment method
* As a (Shipper) I want to delete a payment method
* As a (Shipper) I want to update a payment method

### Invoicing

If you are building your own UI you will want to have a method of sending customers invoices at the desired interval(s) so they can keep an account of their shipping expenses.

Associated user stories should include:

* As a (Shipper) I want to get a daily record of my shipping expenses
* As a (Shipper) I want to get a weekly record of my shipping expenses
* As a (Shipper) I want to get a monthly record of my shipping expenses
* As a (Shipper) I want to get a record of my shipping expenses when a payment is made

### Reporting

Your users will often want to receive reporting on their shipping so they can improve their business practices. Using the data in your system and shipping data from Shippo you can provide them with valuable information to help them succeed.

Examples of Reports requested by Users

* Shipment analysis trends based on time (day, week, month, hour)
* Shipment analysis by carrier and service level for cost, performance, and other factors
* Shipment analysis by costs related to product, destination, origin, etc.

Associated user stories should include:

* As a (Shipper) I want to get a daily report of my shipping \_\_
* As a (Shipper) I want to get a weekly report of my shipping \_\_
* As a (Shipper) I want to get a monthly report of my shipping \_\_


# Designing Your Shipping Solution
Source: https://docs.goshippo.com/partner-integration/design-solution

Review the recommended minimum shipping features to include at launch, from rate shopping and label purchase to tracking.

It is tempting to build a very minimal shipping integration and determine user demands from there. Shippo's research has shown that this often leads to less than desired adoption rates. With almost a decade of experience in the online shipping industry Shippo recommends the following as a minimum set of functionality at launch. These functions fall into two categories: Order Fulfillment, the ability to buy a label and ship a parcel for an order, and Administration, functionality needed to manage payments, carriers, and other administrative functions.

* Label Generation
  * Rate Shopping
  * Single Label Purchase
  * Batch Label Purchase
  * International Label Purchase and Customs Forms
  * Refunding an unused label
  * Creating return labels
  * Tracking
  * Split Shipments
  * Create a Manifest or Scan form
* Administration
  * Carrier account management
  * Webhook Management
  * Parcel Template Management
  * Address Management
  * Payment Account Management
  * Shipment Transaction History

In the section that follows we will explore the use cases and user stories associated with the above features.


# Data flow sequence
Source: https://docs.goshippo.com/partner-integration/flow

View data flow diagrams showing how merchants, platforms, Shippo, and carriers interact during label purchase and tracking.

The following flows represent typical interactions between a Merchant, e-Commerce platform, Carrier, and Shippo.
Use these flows to understand how to design your Shippo integration.
These flows show the flow of data between Shippo and a platform partner using the Shippo API.

<Info>
  **note**

  Dashed lines show dependencies. For example, before the Shippo API can `Return available shipping rates` to the E-commerce Platform, the E-commerce Platform must `Request shipping rate`.
</Info>

## Label purchase flow

```mermaid theme={null}
%%{init: {'theme': 'neutral', 'width': '100%'}}%%
sequenceDiagram
    participant E-commerce Platform as E-commerce<br /> Platform
    participant Merchant Dashboard as Merchant<br /> Dashboard
    participant Shippo API as Shippo<br /> API
    participant Shipping Carrier as Shipping<br /> Carrier
    participant Customer Email/SMS as Customer<br /> Email/SMS
    participant Customer Account Portal as Customer<br /> Account<br /> Portal

    Note left of E-commerce Platform: E-commerce<br /> Checkout &<br /> Label Purchase
    E-commerce Platform ->> Shippo API: Request shipping rates<br /> (Shipments Endpoint)
    Shippo API ->> E-commerce Platform: Return available<br /> shipping rates
    E-commerce Platform ->> Shippo API: Purchase selected<br /> shipping label<br /> (Transactions Endpoint)
    Shippo API -->> E-commerce Platform: Return shipping label<br /> & tracking number <br />via Webhook

    Note left of E-commerce Platform: Provide Tracking<br /> to Merchant
    E-commerce Platform -->> Merchant Dashboard: Display<br /> tracking<br /> number in<br /> dashboard
    Merchant Dashboard ->> Shippo API: Manual lookup<br /> for shipment<br /> status (optional)<br /> (Tracking Endpoint)
    Shippo API -->> Merchant Dashboard: Return shipment<br /> status
    E-commerce Platform -->> Merchant Dashboard: Display<br /> automated<br /> shipment<br /> updates<br /> (optional)

    Note left of E-commerce Platform: Notify Customer
    E-commerce Platform ->> Customer Email/SMS: Send tracking number<br /> & link via Email/SMS
    E-commerce Platform ->> Customer Account Portal: Update tracking number<br /> & link in account portal

    Note left of E-commerce Platform: Customer Tracking
    Customer Email/SMS -->> Shipping Carrier: Redirect<br /> customer<br /> to carrier's<br /> tracking page<br /> (via link)
    Customer Account Portal -->> Shipping Carrier: Redirect customer<br /> to carrier's<br /> tracking page<br /> (via link)

    Note left of E-commerce Platform: Real-time Status<br /> & Handling<br /> Exceptions
    Shipping Carrier ->> Shippo API: Update shipment<br /> status in real-time
    Shippo API ->> E-commerce Platform: Push real-time<br /> status updates
    E-commerce Platform ->> Merchant Dashboard: Display<br /> status & <br />alerts on<br /> exceptions <br /> (e.g., delivery failed)
    E-commerce Platform ->> Customer Email/SMS: Send status updates<br /> or exception alerts <br /> (optional)
    Merchant Dashboard ->> Shipping Carrier: Contact for<br /> resolution on exceptions<br /> (if needed)
```

## Instalabel single call label purchase flow

The following flow includes the purchase of a label using the Shippo [Instalabel](/guides/single-call) single call label generation.

```mermaid theme={null}
%%{init: {'theme':'neutral', 'width': '100%'}}%%
sequenceDiagram
    participant E-commerce Platform as E-commerce<br /> Platform
    participant Merchant Dashboard as Merchant<br /> Dashboard
    participant Shippo API as Shippo<br /> API
    participant Shipping Carrier as Shipping<br /> Carrier
    participant Customer Email/SMS as Customer<br /> Email/SMS
    participant Customer Account Portal as Customer<br /> Account<br /> Portal

    Note left of E-commerce Platform: E-commerce<br /> Checkout &<br /> Label Purchase
    E-commerce Platform ->> Shippo API: Purchase<br /> selected<br /> shipping label<br /> (Transactions Endpoint)
    Shippo API -->> E-commerce Platform: Return shipping<br /> label & tracking number<br /> via Webhook

    Note left of E-commerce Platform: Provide Tracking<br /> to Merchant
    E-commerce Platform -->> Merchant Dashboard : Display<br /> tracking<br /> number in<br /> dashboard
    Merchant Dashboard ->> Shippo API: Manual lookup<br /> for shipment<br /> status<br /> (optional)<br /> (Tracking Endpoint)
    Shippo API -->> Merchant Dashboard: Return shipment status
    E-commerce Platform -->>  Merchant Dashboard : Display<br /> automated<br /> shipment<br /> updates<br /> (optional)

    Note left of E-commerce Platform: Notify Customer
    E-commerce Platform ->> Customer Email/SMS: Send tracking number<br /> & link via Email/SMS
    E-commerce Platform ->> Customer Account Portal: Update tracking number<br /> & link in account portal

    Note left of E-commerce Platform: Customer Tracking
    Customer Email/SMS -->> Shipping Carrier: Redirect<br /> customer<br /> to carrier's<br /> tracking page<br /> (via link)
    Customer Account Portal -->> Shipping Carrier: Redirect<br /> customer<br /> to carrier's<br /> tracking page<br /> (via link)

    Note left of E-commerce Platform: Real-time<br /> Status<br /> & Handling<br /> Exceptions
    Shipping Carrier ->> Shippo API: Update<br /> shipment<br /> status in<br /> real-time
    Shippo API ->> E-commerce Platform: Push real-time status updates
    E-commerce Platform ->> Merchant Dashboard: Display<br /> status<br /> & alerts on<br /> exceptions<br /> (e.g., delivery failed)
    E-commerce Platform ->> Customer Email/SMS: Send status <br />updates or<br /> exception alerts<br /> (optional)
    Merchant Dashboard ->> Shipping Carrier: Contact for <br />resolution on exceptions<br /> (if needed)
```


# Where to Get Information
Source: https://docs.goshippo.com/partner-integration/get-info

Find where to access Shippo technical documentation, API guides, support resources, and reference materials.

This document contains information to get started from a technical perspective. The first thing to note is that our documentation is located in this portal. Use the sidebar to navigate Guides (how things work and how to use them) and the Reference section (code samples and API specifications).

You may also find the information in the Shippo.com support knowledge base useful. There are also some great resources if you are new to shipping at Shippo.com in the Resources section. Please note that some of the information in these two resources is geared toward the users of Shippo's web application, and API usage might differ. These resources are also useful as you consider what your end users might need to help them with shipping.


# Integration Foundation Decisions
Source: https://docs.goshippo.com/partner-integration/int-decisions

Decide between gray label and white label account types and choose your UI approach for your Shippo integration.

These decisions will determine how Shipper accounts will be managed and structured and how the user interface for shipping will be managed.

## Shipper Accounts

This is broken down into two main categories Gray and White label.

* Simply put a Gray label is a co branded integration Shippo manages billing and support and Shippo carrier accounts are available with the major carriers. User authentication is handled through OAuth.
* In a White Label integration the integrator owns the above items and the shipper is unaware of Shippo's involvement in the tech stack. This will require a robust billing and reconciliation system, customer support, and limits the use of Shippo carrier accounts.
  * White Label integrations can leverage the Shippo sub account structure to manage individual Shipper accounts in a segregated fashion. This will allow for a better system for billing reconciliation and carrier management along with other reporting and audit functions.

## User Interface

These are the options available for the User Interface (UI):

1. OAuth into the Shippo web application, this is for Gray Label integrations only and is the simplest path to integration. Shippers will be redirected to the Shippo web app to purchase labels and orders are synced into the web application from an integrator's system.
2. OAuth with Native UI, this still leverages OAuth however some or all of the UI is native to your application. For example, you may build a label purchase workflow but choose to have users update billing and carrier information in the Shippo web application. This option does not apply to White Label integrations.
3. Native UI, this is a user interface and experience where all the aspects of shipping are native to your system. This can apply to both Gray and White Label integrations but is most commonly used by White Label Integrators. Because you are not associating this application with Shippo you will need to manage user accounts and authentication.

For options 2 and 3, Shippo has a SAAS offering called Shipping Elements. This is a UI Shippo builds and maintains and you can integrate using an iFrame. This allows you to rely on Shippo to maintain and update the shipping experience while keeping users inside your application.

## Choosing the right path

As seen above, each integration method has excellent reasons why partners may choose one over the other. To help in deciding which path is right, take a look at the following user stories and select those that are most aligned with your business needs.

* As a (Platform) I want to handle invoicing my customers for shipping costs
* As a (Platform) I want to be able to offer closed carrier registration carriers to my customers
* As a (Platform) I want to be in control of the entire customer experience
* As a (Platform) I want granular access to merchant shipping accounts
* As a (Platform) I want to be able to retrieve account details of an individual merchant
* As a (Platform) I want to be able to update a merchant account
* As a (Platform) I want to avoid all or part of user account maintenance
* As a (Platform) I want my customers to know we are working with Shippo
* As a (Platform) I want to facilitate order fulfillment, but not handle any billing details
* As a Platform, I have significant engineering resources to devote to building a fulfillment workflow for my customers
* As a Platform I have the ability to provide support to my customers when they have questions about order fulfillment

Answering the questions above should give you an idea of which direction you should be leaning when it comes to an authentication method selection when working with Shippo. While your selection here is not binding (partners have migrated in both directions) think deeply on this in the beginning so you are setup for success from the start.


# Shippo API Integration Guide
Source: https://docs.goshippo.com/partner-integration/intro

Overview of the Shippo API Integration Guide for partners adding order fulfillment to e-commerce platforms.

Welcome to the Shippo API Integration Guide, designed for partners who will be using Shippo's APIs to add order fulfillment functionality to e-commerce platforms. This guide is intended to help product managers understand the use cases that Shippo's API will handle, and to provide engineers with the necessary details to build a system to handle each use case.

Shippo's API is trusted by leading e-commerce platforms to streamline their shipping processes and improve their customers' experience. With Shippo's API, you can easily access the best shipping rates, print shipping labels, and track packages all in one place.

This integration guide is divided into several sections that will guide you through the integration process. We will start with an overview of the prerequisites required for successful integration, including the knowledge of programming languages and tools, and access to certain software systems. Next, we will discuss foundational decisions that need to be made to determine how shipping accounts will be handled and UI ownership.

Next, we will provide an in-depth explanation of Shippo's API documentation, including the endpoints, parameters, and responses. We will also outline the various API methods, such as GET, POST, PUT, and DELETE.

The integration process will be explained in detail, providing a step-by-step guide on how to integrate the Shippo API into your e-commerce platform. We will include details on how to authenticate, how to handle errors, and how to ensure the security of the API.

We will provide best practices and tips for integrating Shippo's API into your e-commerce platform, such as code samples, performance optimizations, and handling of edge cases.

Finally, we will provide guidelines on how to test and debug the integration process. We will include details on how to test API endpoints, how to debug issues, and how to troubleshoot errors.

We are confident that this integration guide will be a valuable resource for our partners who want to integrate Shippo's API into their e-commerce platforms. With Shippo's API, you can streamline your shipping process and deliver a better customer experience.


# Prerequisites
Source: https://docs.goshippo.com/partner-integration/prereqs

Set up your Shippo account and generate an API key before you start integrating with the Shippo API.

Before integrating Shippo's API into your e-commerce platform, you will need the following:

* **Shippo Account**: You will need a functional Shippo account to access the API. If you do not have a Shippo account yet, you can sign up for one at [https://goshippo.com/register](https://goshippo.com/register).

* **API Key**: You will also need an API key to authenticate your requests to the API. Complete the steps in [Getting an API key](#getting-an-api-key) to get your API key.

## Getting an API Key

To use Shippo's API, you will need to authenticate your requests with an API key. Here are the steps to obtain an API key:

1. Log in to the Shippo API portal at [https://portal.goshippo.com/api-config/api](https://portal.goshippo.com/api-config/api) using your Shippo credentials.

2. In **Developer keys** under **API configuration**, click **Create new live key** for a live key or click **Create new test key** for a test key.

3. Once you have create an API key, copy it to your clipboard, as it will not be shown again.

4. You can now use the API key to authenticate your requests to Shippo's API by including it in the `Authorization` header of your HTTP requests.

   For example, if your API key is `shippo_test_token`, your `Authorization` header should look like this:
   `Authorization: ShippoToken shippo_test_token`

Please note that you should keep your API key confidential and not share it with unauthorized personnel. If you suspect that your API key has been compromised, you should regenerate it immediately from the Shippo dashboard.

There are two key decisions that will form the foundation of a Shippo integration. The first is how shipper accounts will be created and managed and the second is how the user interface will be built and maintained. Once these two foundational points are determined User Stories can be examined to determine the priority and need for various aspects of Shipping


# Sandbox testing
Source: https://docs.goshippo.com/partner-integration/sandbox-testing

Set up a sandbox environment to build and test your Shippo integration using test API tokens and dedicated accounts.

A sandbox environment is a place for you to build and test your Shippo integration without affecting your production environment.
Shippo does not provide a dedicated sandbox. We recommend setting up a dedicated Shippo account and using that as your sandbox. Because there is no charge for additional Shippo accounts this is the easiest way to structure a testing environment. You can also use this account for further testing as development continues after the integration launches.

We recommended that this account is attached to a distribution list or alias, like [ShippoTesting@YourCompany.com](mailto:ShippoTesting@YourCompany.com).

Depending on how your team works, individual developers could also get their own account.

## Test API Token vs Live API Token

For a majority of the testing an integration partner will need a Test API Token can be used. This will prevent the purchase of actual labels and simulate label generation and other functions. Test tokens do have limitations when it comes to:

* Retrieving real rates
* Manifesting
* Tracking
* Address validation

Live API tokens should be used for final testing before a launch and will allow a partner to complete real world end to end testing, including purchase, tracking, and refunding of live labels.

## Carrier testing

Much like general testing a test API token can assist with generic testing of carriers. However, a test token can not be relied on for accurate rating because they do not always call the carrier for live rates and use placeholder rates. To test rates and rate cards use a live API token and simply do not purchase the labels or request refunds. Refunds do not cancel labels but will request a refund which can take up to 14 days.

### Carrier test mode

Carriers can be placed in [test mode](https://support.goshippo.com/hc/en-us/articles/360003902611-How-to-Use-Test-Mode-Account-Sandbox-in-Shippo) in the Shippo.com web application for testing. This will prevent purchase of live labels and should be used with caution on live accounts as the carrier is disabled from label purchase.

<Info>
  **Note**

  At present, FedEx does not support test mode and requires a FedEx account specifically setup for testing. Contact your FedEx account manager for support in setting up a FedEx test account.
</Info>


# Test plan
Source: https://docs.goshippo.com/partner-integration/test-plan

Build a test plan for your Shippo integration with scenarios for address validation, carrier setup, rating, and labels.

To support your Shippo integration, we recommend developing a test plan. A test plan is a roadmap for testing how different parts of your application works with an integration.
Use the test scenarios below as a framework to build your test plan.

## Testing setup

Different integration types will be best structured as follows:

* [White Label](/guides/integration-paths#white-label-platform-accounts)
  * Two accounts should be established, one for production and one for testing. These are both best setup as accounts where many users can access the email such as an alias. This prevents problems with staff transitions and password resets. Individuals or teams can also use their own accounts as needed.
* [White Label Platform](/guides/integration-paths#white-label-platform-accounts)
  * A top level account will be set up and established as the parent account. This account is not generally used for rating and label generation but is the structure for tenant accounts. Tennant accounts should be used for testing and development purposes as this level is where production labels will be managed.
* [Gray Label](/guides/integration-paths#gray-label-oauth)
  * Because gray label integrations rely on Oauth for tracking and attribution there is no need for a strict account structure. Every account will be stand alone and linked to an integration by the Oauth registration process. It is best that testing for production purposes is performed by registering through Ouath just as a customer would.
    Please Note: Testing through Oauth will require a valid credit card for registration.

## Testing scenarios

Below are examples of scenarios to consider when establishing a testing plan.
Use this guide to test a new carrier integration. Based on Shippo's experience with API integrations, these are the minimum tests your integration must pass before deploying for production.

Not all tests will apply to the carrier or integration you are testing, review the test scripts and determine which ones apply to your business.

If you are preparing to release into production with this carrier, run these test scripts using a production account. Remember to void any labels created during testing to avoid being billed for them. For pre-production testing it is best to use the [test mode API token](/guides/testing) to avoid being charged for shipments.

You will need the following:

* [Carrier Account Information](https://goshippo.com/carriers) or an activated Shippo carrier account
* A list of all [service levels](/api-reference/service-groups/list-all-service-groups) you are supporting for the carrier.
* Required shipping fields: a valid from address, a valid to address, parcel dimensions.
  * You will need to account for domestic and international addresses when applicable
* An understanding of the capabilities integrated for the carrier. For example, not all carriers support manifests or custom's functionality.

## Suggested Tests

### Validate an Address

<Info>
  **Note**

  Address validation will not work with your test API token. You must use your live API token.
</Info>

| Test the ability to:             | Expected Result                                                            | Test Result | Notes/Saved ID |
| -------------------------------- | -------------------------------------------------------------------------- | ----------- | -------------- |
| Validate a known valid address   | You should receive a positive response indicating the address is valid     |             |                |
| Validate a known invalid address | You should receive a negative response indicating the address is not valid |             |                |

### Add A Carrier

| Test the ability to:                                       | Expected Result                                                        | Test Result | Notes/Saved ID |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- | -------------- |
| Add the carrier using the API                              | You should receive a positive response indicating the carrier is added |             |                |
| Add the carrier to a Merchant account for the Platform API | You should receive a positive response indicating the carrier is added |             |                |

### Get A List of Carriers

| Test the ability to:                                                            | Expected Result                                                                  | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | -------------- |
| Retrieve a list of carriers for the Shippo account the new carrier was added to | You should receive a positive response listing all the carriers for that account |             |                |

### Get A Rate

| Test the ability to:                                                          | Expected Result                                                                                          | Test Result | Notes/Saved ID |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------- | -------------- |
| Get a rate for the carrier domestically without specifying a service level    | You should receive a positive response with rates for all the service levels appropriate to the carrier. |             |                |
| Get a rate for the carrier internationally without specifying a service level | You should receive a positive response with rates for all the service levels appropriate to the carrier. |             |                |
| Get a rate for the carrier domestically with bad To address information       | You should receive a response with an error indicating the address failure                               |             |                |
| Get a rate for the carrier domestically with bad From address information     | You should receive a response with an error indicating the address failure                               |             |                |

### Purchase Label from Existing Rate

| Test the ability to:                                                                  | Expected Result                                                                                                                                                                                                                                   | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- |
| Purchase a label for the carrier domestically using the Rate Id from a previous test. | You should receive a positive response with the label purchased. \* save this label id for later use\*\* save this label's tracking number for later use                                                                                          |             |                |
| Purchase a label for the carrier internationally using the Rate Id from previous test | You should receive a positive response with the label purchased.<br />Take care to note the proper customs information is returned in the response. \* save this label id for later use<br />\*\* save this label's tracking number for later use |             |                |

### Purchase a Label in One Step

| Test the ability to:                                                            | Expected Result                                                                                        | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------- | -------------- |
| Purchase a label for the carrier domestically                                   | You should receive a positive response with the appropriate label. \*save this label id for future use |             |                |
| Purchase a label for the carrier internationally                                | You should receive a positive response with the appropriate label. \*save this label id for future use |             |                |
| Purchase a label for the carrier domestically with bad To address information   | You should receive a response with an error indicating the address failure                             |             |                |
| Purchase a label for the carrier domestically with bad From address information | You should receive a response with an error indicating the address failure                             |             |                |

### Refund a Label

| Test the ability to:                                                                 | Expected Result                                                                            | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------- | -------------- |
| Refund a label for the carrier domestically using the Label ID from a previous step. | You should receive a positive response indicating the label has been canceled and refined. |             |                |

### Track a Label

<Info>
  **Note**

  Tracking will not work with your test API token. You must use your live API token.
</Info>

| Test the ability to:                                                                  | Expected Result                                                       | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- | -------------- |
| Track a label for the carrier domestically using the Rate Id from a previous test.    | You should receive a positive response with the tracking information. |             |                |
| Track a label for the carrier internationally using the Rate Id from a previous test. | You should receive a positive response with the tracking information. |             |                |

### Schedule a Pickup

| Test the ability to:                                                                  | Expected Result                                                                                                                                                                                                                 | Test Result | Notes/Saved ID |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- |
| Schedule a pickup using a Label Id from a previous step.                              | You should receive a positive response with the scheduled pickup information.<br />Because there is no programmatic way to cancel a pickup in the API if this is done in production, follow the carrier's directions to cancel. |             |                |
| Track a label for the carrier internationally using the Rate Id from a previous test. | You should receive a positive response with the tracking information.                                                                                                                                                           |             |                |

### Manage Batch Shipping

| Test the ability to:                                                                                                              | Expected Result                                                                                     | Test Result | Notes/Saved ID |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------- | -------------- |
| Create a batch.                                                                                                                   | You should receive a positive response with the batch information. Save the Batch Id for later use. |             |                |
| Retrieve a batch.                                                                                                                 | You should receive a positive response with the batch information.                                  |             |                |
| Add a shipment to a batch using the shipment id from a previous step. Perform this twice so the batch has more than one shipment. | You should receive a positive response with the shipment added to the batch.                        |             |                |
| Remove a shipment from a batch using a shipment from the previous step                                                            | You should receive a positive response with the shipment removed from the batch.                    |             |                |
| Purchase a batch.                                                                                                                 | You should receive a positive response with the batch purchase information.                         |             |                |

### Test Carrier Service Levels

| Test                                                                                                                                   | Result                                                                           | Test Result | Notes/Saved ID |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | -------------- |
| Create a rate for each service level that will be used for this carrier. Repeat as many times as necessary to test all service levels. | You should receive a positive response with the shipment for each service level. |             |                |

### Create a Manifest

| Test               | Result                                                                | Test Result | Notes/Saved ID |
| ------------------ | --------------------------------------------------------------------- | ----------- | -------------- |
| Create a manifest. | You should receive a positive response with the manifest information. |             |                |

### Create a Webhook

| Test                                      | Result                                                                                           | Test Result | Notes/Saved ID |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | -------------- |
| Create a webhook for tracking a shipment. | You should receive a positive response with the webhook created and updates to tracked packages. |             |                |
| Cancel a label from a previous shipment.  | Your webhook should receive the update that the shipment is canceled.                            |             |                |

<Info>
  **Note**

  If you are testing in production, remember to [cancel any labels](/billing-and-invoices/refunding-labels) that were purchased to avoid being charged.
</Info>


# Platform Accounts
Source: https://docs.goshippo.com/platform-accounts/platform-accounts

Learn how Platform Accounts let you create and manage Managed Shippo Accounts for your marketplace or 3PL customers.

## What is a Platform Account?

Marketplaces, e-commerce platforms, and third-party logistics providers often want to offer built-in shipping functionality to their customers. They may also need to track shipping data on a per-customer basis. Without a Platform Account, managing this process can require complex mapping and logic within your code.

A Platform Account allows you to customize the shipping capabilities that are offered to your customers by allowing you to configure headless Managed Shippo Accounts for each customer.

For more information about integration paths and different account types, review our guide on [Choosing your integration path](/guides/integration-paths).

<Info>
  **note**

  Carriers including USPS, UPS, and Canada Post **require** e-commerce marketplaces to use Managed Shippo accounts for their merchants. If you run a marketplace with merchants, use a Shippo Platform Account.
</Info>

## What are Managed Shippo Accounts?

Managed Shippo Accounts are headless accounts (they do not have a Shippo website login) that represent your customers. You own your Managed Shippo Accounts and interact with them only through the Shippo API.
Managed Shippo Accounts are opaque to your end customers, meaning they don't need to create their own Shippo login or have a billing relationship with Shippo.
Using Managed Shippo Accounts, you can control shipping settings for your customers while the shipping experience for your end users remains native and seamless.

Administering your customers as Managed Shippo Accounts allows you to do the following.

* Customize multiple customers settings behind the scenes that simplifies managing customers at scale . For example,  setting up specific carrier accounts to be used for each customer.
* Accurately report on each customer's activity. For example, obtaining each customer's associated shipments and other relevant data.

<Info>
  **Note**

  Do not use Managed Shippo Accounts if you want your customers to self-manage their shipping settings on Shippo or have a direct billing relationship with Shippo. Instead, you should consider using an [OAuth integration](/o-auth-integrations/o-auth) for a co-branded experience.
</Info>

## Who uses Managed Shippo Accounts?

### Platform Accounts for e-commerce marketplaces

E-commerce marketplaces are platforms where multiple third-party sellers can list their products or services, and buyers can browse and purchase them. Popular examples include Shopify and eBay. E-commerce platforms use Platform Accounts to provide Managed Accounts for each of their merchants, giving merchants seamless access to shipping infrastructure. This also makes it easy to track and bill each merchant individually.

### Platform Accounts for 3PLs

A third-party logistics service (3PL), sometimes referred to as fulfillment centers or fulfillment warehouses, are businesses that offer outsourced logistics services to other businesses. These services can include a wide range of functions related to the storage, transportation, and distribution of goods. A popular example of a 3PL is ShipBob.

3PLs use platform accounts to provide managed accounts for each of the businesses they support. This allows them the flexibility to offer customized shipping options for each of the businesses they support.


# Migrating from Platform API to Shippo API
Source: https://docs.goshippo.com/platform-accounts/platform-api-migrate

Migrate your integration from the Shippo for Platforms API to the Shippo API with updated URLs, headers, and endpoints.

If you already use the [Shippo for Platforms API](https://goshippo.com/shippo-for-platforms/) to support your merchants, you may choose to update your integration to take advantage of the Shippo API. Follow this guide to learn how.

### Change your Base URL

Previously, Shippo for Platforms used the base URL `https://platform-api.goshippo.com`. To use the Shippo API, change your base URL to `https://api.goshippo.com/`.

### Reference Merchants using a header, not a parameter

Previously, you referenced merchants using a parameter, for example:

```shell theme={null}
curl https://platform-api.goshippo.com/merchants/{MerchantId}/addresses/
```

where `{MerchantId}` is the object ID of your merchant.

To use Managed Shippo Accounts in the Shippo API, you reference your Managed Account merchant using a header element. For example:

```shell theme={null}
curl https://api.goshippo.com/addresses/ -H 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a'
```

where `SHIPPO-ACCOUNT-ID` is the object ID of your Managed Account merchant.

### Renamed endpoints

The following endpoints have changed. Follow the examples in our reference documentation to update your integration.

* [Merchant](https://platform-api-docs.goshippo.com/#tag/Merchants) has been updated to [Shippo Accounts](/api-reference/shippo-accounts/list-all-shippo-accounts).
* [Carrier Own Accounts](https://platform-api-docs.goshippo.com/#tag/Carrier-Own-Accounts) has been updated to [Carrier Accounts](/api-reference/carrier-accounts/list-all-carrier-accounts).
* [Shippo Carrier Accounts](https://platform-api-docs.goshippo.com/#tag/Carrier-Master-Accounts) has been updated and is now part of [Carrier Accounts](/api-reference/carrier-accounts/list-all-carrier-accounts).

### Example

To list all the address stored in a merchant's account

```shell Shippo API theme={null}
curl https://api.goshippo.com/addresses/ \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>'
```

```shell Platform API theme={null}
curl https://platform-api.goshippo.com/merchants/{MerchantId}/addresses/ \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json'
```

<Info>
  **Note**

  You do not need to migrate any data from your existing Platforms account.
</Info>


# Upgrade to a Platform Account
Source: https://docs.goshippo.com/platform-accounts/platform-upgrade-account

Follow these steps to upgrade your Shippo account to a Platform Account and start using Managed Shippo Accounts.

To start using Managed Shippo Accounts, you must convert your existing Shippo Account to a Platform Account. Follow these steps.

<img alt="step 1 icon" /> If you don't already have one, create a [Shippo account](https://apps.goshippo.com/join).

<img alt="step 2 icon" /> Contact our [partnership support team](https://goshippo.com/become-a-shippo-partner) to guide you through the process of setting up your Platform Account. This can take a number of days to complete.

## Upgrade to Platform Account flow

The following steps show how to convert your Shippo account to a Platform account and how to use managed accounts.

<br />

<br />

```mermaid theme={null}
%%{init: {'theme': 'neutral', 'width': '100%','curve' : 'stepBefore'}}%%
flowchart LR
    A[Step 1. Contact Shippo to<br /> convert account<br /> to Platform account] --> T1( )
    T1( ) --> B[<a href='/platform-accounts/platform-using-accounts#create-a-managed-shippo-account-for-your-customer'>Step 2</a>. Create a<br /> Managed account]
    B --> C[<a href='/platform-accounts/platform-using-accounts#add-a-carrier-account'>Step 3</a>. Add a carrier<br /> to a Managed account]
    C --> T2( )
    T2 --> T1
    T2( ) --> D[<a href='/platform-accounts/platform-using-accounts#create-a-shipment-and-generate-rates'>Step 4</a>. Create<br /> Shipment]
    D --> E[<a href='/platform-accounts/platform-using-accounts#purchase-a-label'>Step 5</a>. Create<br /> Transaction]
```

<br />

<br />

<Info>
  **note**

  When converting your Shippo account to a Platforms account, you must compete these additional steps to enable carrier support.

  1. Your carriers will not automatically be transferred from your Shippo account to Platform account. You must contact your account manager to enable your preferred carriers on your Platform account.
  2. Managed Shippo Accounts do **NOT** automatically inherit access to carriers from your Platform account. To give your Managed Shippo Accounts access to a carrier, you must [add a carrier account to each Managed Account individually](/platform-accounts/platform-using-accounts#how-does-it-work). You must do this for each carrier you want your Platform account to have access to.
</Info>

Below is a sample email template you can use to request an upgrade to a platform account from your account manager.

```
Hi,

I need to convert my Shippo account into a Platform account. I've included all requisite information below.

-   Company Name:
-   Contact Email:
-   Shippo carriers to accessible on account:
-   Own carriers to be accessible on account: 

Please let me know if you have any questions.

Thanks,

<Your Name>

```

When your account has been upgraded, you can begin using Managed Shippo Accounts.


# Using your Platform Account
Source: https://docs.goshippo.com/platform-accounts/platform-using-accounts

Create Managed Shippo Accounts, add carriers, generate rates, and purchase labels for your platform customers.

## 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>`.

<Info>
  **Note**

  This is different from making authorized API calls on behalf of your customers through an [OAuth integration](/o-auth-integrations/o-auth). 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.
</Info>

## 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)

### Create a Managed Shippo Account for your customer

**Request:**

```shell Create account request theme={null}
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 Create account response theme={null}
{
  "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`.

### 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](/carriers/carrier-accounts#connecting-shippo-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](/api-reference/carrier-accounts/add-a-shippo-carrier-account) endpoint.

**Request:**

```shell Add a Shippo carrier account request theme={null}
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 Add a Shippo carrier account response theme={null}
{
  "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](/api-reference/carrier-accounts/create-a-new-carrier-account) 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.

<Info>
  **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](/carriers/carrier-accounts) guide to identify which parameters are required for your carrier.
</Info>

**Request:**

```shell Add your own carrier account request theme={null}
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 Add your own carrier account response theme={null}
 "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"
           }
```

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

```shell Create a Shipment request for a Managed Account theme={null}
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 Create a Shipment for a Managed Account response theme={null}
{
   {
  "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": []
}
```

### Purchase a label

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

**Request:**

```shell Purchase a label for a Managed Account request theme={null}
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:**

```json Purchase a label for a Managed Account response theme={null}
{
    "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.


# Alcohol shipments
Source: https://docs.goshippo.com/shipments/alcohol-shipments

Learn how to create shipping labels for alcohol shipments using the extras field in the Shippo Shipment object.

Shippo supports creating labels for shipping alcohol by specifying options in the `extras` field of the Shipment object.

## Creating an alcohol shipment

To create a label for a shipment that will contain alcohol, you will need to specify options in the Shipment `extra` field.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_Token>"\
    -d address_from="d799c2679e644279b59fe661ac8fa488"\
    -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
    -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
    -d extra='{"alcohol": {"contains_alcohol": true, "recipient_type": "consumer"}}'\
    -d async=false
```

In the response you'll get your usual Shipment object with all of the available rates for your alcohol shipment.

```json theme={null}
{
    "address_from": {
        "city": "San Francisco",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Mr Hippo",
        "object_id": "b631001acb534e2bbf7cea94adfd2d00",
        "phone": "4151234567",
        "state": "CA",
        "street1": "965 Mission St",
        "street2": "APT 572",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "94103"
    },
    "address_return": {
        "city": "San Francisco",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Mr Hippo",
        "object_id": "b631001acb534e2bbf7cea94adfd2d00",
        "phone": "4151234567",
        "state": "CA",
        "street1": "965 Mission St",
        "street2": "APT 572",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "94103"
    },
    "address_to": {
        "city": "Brooklyn",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Billy Bob",
        "object_id": "13d8b016de1c4befbdff900cd05ad2da",
        "phone": "4151234567",
        "state": "NY",
        "street1": "206 1ST ST",
        "street2": "STE 202",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "11232"
    },
    "carrier_accounts": [
        "078870331023437cb917f5187429b093"
    ],
    "customs_declaration": null,
    "extra": {
        "alcohol": {
            "contains_alcohol": true,
            "recipient_type": "licensee"
        }
    },
    "messages": [],
    "metadata": "",
    "object_created": "2017-08-03T17:54:54.006Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2017-08-03T17:54:54.006Z",
    "parcels": [
        {
            "distance_unit": "in",
            "extra": [],
            "height": "3.0000",
            "length": "10.0000",
            "line_items": [],
            "mass_unit": "lb",
            "metadata": "",
            "object_created": "2017-08-03T17:54:53.976Z",
            "object_id": "6fb5951a0900439b8770bc1814ee5528",
            "object_owner": "shippotle@shippo.com",
            "object_state": "VALID",
            "object_updated": "2017-08-03T17:54:54.024Z",
            "template": null,
            "test": true,
            "value_amount": null,
            "value_currency": null,
            "weight": "1.0000",
            "width": "3.0000"
        }
    ],
    "rates": [
        {
            "amount": "14.16",
            "amount_local": "14.16",
            "arrives_by": null,
            "attributes": [
                "BESTVALUE",
                "CHEAPEST",
                "FASTEST"
            ],
            "carrier_account": "078870331023437cb917f5187429b093",
            "currency": "USD",
            "currency_local": "USD",
            "duration_terms": "",
            "estimated_days": 5,
            "messages": [],
            "object_created": "2017-08-03T17:54:56.057Z",
            "object_id": "d870ae7efc7c45eabf097986d45d4f09",
            "object_owner": "shippotle@shippo.com",
            "provider": "FedEx",
            "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png",
            "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
            "servicelevel": {
                "name": "Ground",
                "terms": "",
                "token": "fedex_ground"
            },
            "shipment": "6781b0124d2d4f8cbdd24bd589c61460",
            "test": true,
            "zone": "8"
        }
    ],
    "shipment_date": "2017-08-03T17:54:53.975Z",
    "status": "SUCCESS"
}
```

## Create an alcohol shipment label

You can then use any rate `object_id` that was returned to create a transaction and get your shipping label:

cURL

```shell theme={null}
curl https://api.goshippo.com/transactions\
    -H "Authorization: ShippoToken <API_Token>"\
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
```

FedEx returns two labels that *both* need to be placed on the shipment. You will only receive one `label_url` that is two pages long in the transaction object.

Your transaction response will look the same as any other shipment:

```json theme={null}
{
    "commercial_invoice_url": null,
    "eta": null,
    "label_url": "https://shippo-delivery-east.s3.amazonaws.com/fe52964dbfe449efb6210f0caa9fdee8.pdf?Signature=aF9ujJ%2BOV5pJc24XoTuKeBmfJCQ%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "messages": [],
    "metadata": "",
    "object_created": "2017-08-03T17:55:44.347Z",
    "object_id": "fe52964dbfe449efb6210f0caa9fdee8",
    "object_owner": "shippotle@shippo.com",
    "object_state": "VALID",
    "object_updated": "2017-08-03T17:55:46.086Z",
    "order": null,
    "parcel": "6fb5951a0900439b8770bc1814ee5528",
    "rate": "d870ae7efc7c45eabf097986d45d4f09",
    "status": "SUCCESS",
    "test": false,
    "tracking_number": "794609767977",
    "tracking_status": "UNKNOWN",
    "tracking_url_provider": "https://www.fedex.com/apps/fedextrack/?action=track&cntry_code=us&trackingnumber=794609767977"
}
```

## Supported carriers & services

The following carriers services are supported for alcohol shipments.

**FedEx**

* Ground
* Home Delivery
* Express Saver
* 2 Day
* 2 Day A.M.
* Standard Overnight
* Priority Overnight
* First Overnight


# Batch label creation
Source: https://docs.goshippo.com/shipments/batch-label-creation

Create and purchase up to 10,000 shipping labels in a single API request using the Shippo Batch endpoint.

The Batch endpoint allows you to create and purchase up to 10,000 shipments in a single API request.

There are three main steps to the Batch workflow:

<img alt="step 1 icon" />  [Create the batch](#creating-the-batch): POST a list of shipments to be purchased with one API call

<img alt="step 2 icon" />  [Fix validation issues](#fix-validation-issues) , if any: after creating a batch, Shippo validates the shipment data. Any shipments that failed validation need to be fixed

<img alt="step 3 icon" />  [Purchase the batch](#purchase-the-batch): purchase labels for all shipments in the batch with one API call

## Creating the batch

The Batch Object contains an array of BatchShipment. The [BatchShipment Object](/api-reference/batches/create-a-batch) acts as a wrapper around the Shipment Object, containing shipment-specific service level information such as carrier and service level.

To create a batch, send a JSON request to the [Batch endpoint](/api-reference/batches/create-a-batch) with an array of BatchShipment objects.

The following is an example of the request.

```json theme={null}
{
    "batch_shipments": [
        {
            "servicelevel_token": "usps_priority_express",
            "shipment": {
                "address_from": "d2ce085dd3734a22b20c6df36a63aa07",
                "address_to": "8172f0a35d6d4ff6a37e7a082e4da7a6",
                "parcels": [
                    "f93c159892f54402bf14a50488ca2c36"
                ]
            }
        },
        {
            "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
            "servicelevel_token": "fedex_2_day",
            "shipment": {
                "address_from": "d2ce085dd3734a22b20c6df36a63bb07",
                "address_to": "8172f0a35d6d4ff6a37e7a082e4da7b6",
                "parcels": [
                    "f93c159892f54402bf14a50488ca2c38"
                ]
            }
        }
    ],
    "default_carrier_account": "33391cd4ab974f478f55dc08b5c8e3b3",
    "default_servicelevel_token": "usps_priority",
    "label_filetype": "PDF_4x6",
    "metadata": "BATCH #170"
}
```

[This request is done asynchronously.](/api-concepts/asynchronus-api-call) An empty Batch object is returned first while BatchShipments are created in the background. Since creating many Shipments can take some time, asynchronous requests will let you process other tasks in the meantime.

You can opt to be notified when the Shipment creation is complete through a webhook or polling. You can set up your webhooks from [your Shippo dashboard](https://apps.goshippo.com/login?next=/user/apikeys/), by setting the event type to `batch_created`. For more information, see our [Webhooks tutorial.](/tracking/webhooks)

Here is a sample of the empty response.

```json theme={null}
{
    "batch_shipments": {
        "count": 0,
        "next": null,
        "previous": null,
        "results": []
    },
    "default_carrier_account": "bf8ef2b8aba24ac0b2efde9c72349919",
    "default_servicelevel_token": "usps_priority",
    "label_filetype": "PDF_4x6",
    "label_url": [],
    "metadata": "BATCH #170",
    "object_created": "2016-08-09T16:52:47.626Z",
    "object_id": "c6937c15a99440758b75cde7f18e2a0d",
    "object_owner": "support@shippo.com",
    "object_results": {
        "creation_failed": 0,
        "creation_succeeded": 0,
        "purchase_failed": 0,
        "purchase_succeeded": 0
    },
    "object_updated": "2016-08-09T16:52:47.626Z",
    "status": "VALIDATING"
}
```

## Default service levels vs. per-shipment service levels

When creating your Batch, you can choose to apply one carrier service level for all your Shipments, or specify the service level on a per-shipment bases. [Please see our service level tokens in the API reference guide.](/api-reference/service-groups/list-all-service-groups)

If you want to set one service levels for all the Shipments in your batch, you can specify the service level token with `default_servicelevel_token` field in your Batch request.

This field can be overridden on a per-shipment basis by filling out the optional `servicelevel_token` field on the BatchShipment object.

The following is an example of this behavior:

```json theme={null}
{
    "batch_shipments": [
        {
            "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
            "servicelevel_token": "fedex_2_day",
            "shipment": {
                "address_from": "d2ce085dd3734a22b20c6df36a63aa07",
                "address_to": "8172f0a35d6d4ff6a37e7a082e4da7a6",
                "parcels": [
                    "f93c159892f54402bf14a50488ca2c36"
                ]
            }
        }
    ],
    "default_carrier_account": "33391cd4ab974f478f55dc08b5c8e3b3",
    "default_servicelevel_token": "usps_priority",
    "label_filetype": "PDF_4x6",
    "metadata": "BATCH #170"
}
```

## Fix validation issues

Once the Batch Object is created, the status will change from VALIDATING to either VALID or INVALID. If the status is INVALID, that means some BatchShipments in the Batch have errors that need to be fixed before you can purchase labels.

To find invalid BatchShipments in the Batch, set the `object_results` query parameter on the Batch endpoint to filter by Shipments that have failed. The following is an example of using the `object_results` query parameter:

```shell theme={null}
curl https://api.goshippo.com/batches/<BATCH_OBJECT_ID>?page=2&object_results=creation_failed\
-H "Authorization: ShippoToken <PRIVATE_TOKEN>"
```

The `object_results` query parameter accepts the following values:

* creation\_failed
* creation\_succeeded
* purchase\_succeeded
* purchase\_failed

You can remove invalid BatchShipment objects by sending a PUT request with the invalid BatchShipment object IDs to the following endpoint:

```
https://api.goshippo.com/batches/<BATCH OBJECT ID>/remove_shipments
```

Here is what the sample request should look like:

```json theme={null}
[
    "aa7dea463a5a48b0b8fb21f90e72d779",
    "f11b46440c144ce3b97fb5ddf02b8c71",
    "5400f9078f764b1bbb121bcd08de127f",
    "2ab2b452392545908d2cef8861a39c35"
]
```

Or you can add fixed or new shipments to the batch by passing a POST request with a list of BatchShipment objects to the endpoint:

```
https://api.goshippo.com/batches/<BATCH OBJECT ID>/add_shipments
```

Here's a sample of what the request payload should look like:

```shell theme={null}
[
    {
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "fedex_2_day",
        "shipment": {
            "address_from": "d2ce085dd3734a22b20c6df36a63aa07",
            "address_to": "8172f0a35d6d4ff6a37e7a082e4da7a6",
            "parcels": [
                "f93c159892f54402bf14a50488ca2c36"
            ]
        }
    },
    {
        "carrier_account": "33391cd4ab974f478f55dc08b5c8e3b3",
        "servicelevel_token": "usps_priority_express",
        "shipment": {
            "address_from": "d2ce085dd3734a22b20c6df36a63aa07",
            "address_to": "4f406a13253945a8bc8deb0f8266b245",
            "parcels": [
                "ec952343dd4843c39b42aca620471fd5"
            ]
        }
    }
]
```

Once all shipments have been fixed, identified by the VALID Batch status, you can then proceed to purchase the Batch.

## Purchase the batch

To purchase the batch, simply send an empty POST request to the endpoint:

```
https://api.goshippo.com/batches/<BATCH OBJECT ID>/purchase
```

Here's the purchase response:

```shell theme={null}
{
    "batch_shipments": {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
                "messages": [],
                "metadata": "",
                "object_id": "40f2cf49a3464614b998cc0eb61e768d",
                "servicelevel_token": "fedex_2_day",
                "shipment": "6a2579a51e4f4e49a5eb5d9c6853bd39",
                "status": "VALID",
                "transaction": null
            },
            {
                "carrier_account": null,
                "messages": [],
                "metadata": "",
                "object_id": "b9a42cb3897c4bcda64d7cf0933645df",
                "servicelevel_token": "usps_priority_express",
                "shipment": "2f7b9705c7004396bb1e35ebcf0a3c25",
                "status": "VALID",
                "transaction": null
            }
        ]
    },
    "default_carrier_account": "bf8ef2b8aba24ac0b2efde9c72349919",
    "default_servicelevel_token": "usps_priority",
    "label_filetype": "PDF_4x6",
    "label_url": [],
    "metadata": "BATCH #170",
    "object_created": "2016-08-09T16:52:47.626Z",
    "object_id": "c6937c15a99440758b75cde7f18e2a0d",
    "object_owner": "support@shippo.com",
    "object_results": {
        "creation_failed": 0,
        "creation_succeeded": 2,
        "purchase_failed": 0,
        "purchase_succeeded": 0
    },
    "object_updated": "2016-08-09T16:58:41.060Z",
    "status": "PURCHASING"
}
```

This step is done asynchronously as well. You can [register a webhook](https://apps.goshippo.com/login?next=/user/apikeys/) with the event type `batch_purchased` to get push notifications when your labels are ready. Again, for more information, see our [Webhooks tutorial.](/tracking/webhooks)

If there are any failed transactions, you can find them directly with the `object_results=purchase_failed`query parameter.

Once your purchases are complete, you will be able to download a merged PDF file with the labels. Each PDF file will contain up to 100 labels, the `label_url` field will contain an array of PDF files.


# Drop off and Pickup
Source: https://docs.goshippo.com/shipments/dropoff-pickup

Learn how to create drop-off shipments and schedule carrier pickups using the Shippo API, including QR code support.

## Drop off

A drop off is a location where you can bring your parcel, with a printed label, to be collected by your carrier and delivered to its destination. This is a service that is offered by some carriers. Drop off locations can be places like shipping centers, lockers, or retail locations.

### Create a drop off shipment

You can create drop off shipment using a carrier with a drop off [service level](/api-reference/service-groups/list-all-service-groups). Review our [carriers](/carriers/carrier-capabilities) to see which support drop offs.

Some carriers support creating a scannable code like a barcode or QR code that you can bring to your drop off location without printing a label. This code can be presented at the drop off location using a user's mobile device and the appropriate shipping label can be printed and attached to the parcel. This is particularly useful for users without printing facilities. To request a scannable code, set  `extra.qr_code_requested` to `true`.

```shell Create shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    
  "address_from":{
    "name": "Mr. Hippo",
    "company": "",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "4151234567",
    "email": "mrhippo@goshippo.com",
    "is_residential": null
   },
   "address_to": {
    "name": "Mrs. Hippo",
    "company": "",
    "street1": "1092 Indian Summer Ct",
    "city": "San Jose",
    "state": "CA",
    "zip": "95122",
    "country": "US",
    "phone": "4159876543",
    "email": "mrshippo@goshippo.com",
    "is_residential": null

    },
   "parcels": {
    "length": "10",
    "width": "10",
    "height": "10",
    "distance_unit": "in",
    "weight": "1",
    "mass_unit": "lb",
    "metadata": "Customer ID 123456"
  },
    "extra": {
        "reference_1": "Created on",
        "reference_2": "Shippo",
        "qr_code_requested": true
    },
    
    "metadata": "Customer ID 123456",
    "carrier_accounts": ["<your carrier account object_id>"],
    "async": false
}'
```

```json Create shipment response theme={null}
{
    "object_id": "06bee61d141545d08690631fbb27f602",
    "object_created": "2024-06-25T21:41:45.870Z",
    "object_updated": "2024-06-25T21:41:46.148Z",
    "object_owner": "mrhippo@goshippo.com",
    "test": false,
    "metadata": "Customer ID 123456",
    "messages": [],
    "extra": {
        "qr_code_requested": true,
        "reference_1": "Created on",
        "reference_2": "Shippo"
    },
    "order": null,
    "carrier_accounts": [
        "425b61f50b3642948fb3afa8b3687581"
    ],
    "address_from": {
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "company": "",
        "is_residential": null,
        "test": false,
        "object_id": "dc9ab83e3c9d430e9826cf1bea496fac",
        "is_complete": true,
        "validation_results": {}
    },
    "address_to": {
        "name": "Mrs. Hippo",
        "street1": "1092 Indian Summer Ct",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "mrshippo@goshippo.com",
        "company": "",
        "is_residential": null,
        "test": false,
        "object_id": "81db78275d774cfd81bc8f51e8e4e5f4",
        "is_complete": true,
        "validation_results": {}
    },
    "parcels": [
        {
            "object_owner": "mrhippo@goshippo.com",
            "object_state": "VALID",
            "mass_unit": "lb",
            "template": null,
            "extra": {},
            "metadata": "Customer ID 123456",
            "test": false,
            "object_id": "27a76dad79a84655add8eda8866b397e",
            "object_created": "2024-06-25T21:41:45.870Z",
            "object_updated": "2024-06-25T21:41:45.870Z",
            "length": "10.0000",
            "width": "10.0000",
            "height": "10.0000",
            "distance_unit": "in",
            "weight": "1.0000",
            "line_items": []
        }
    ],
    "status": "SUCCESS",
    "shipment_date": "2024-06-25T21:41:45.870Z",
    "address_return": {
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "company": "",
        "is_residential": null,
        "test": false,
        "object_id": "dc9ab83e3c9d430e9826cf1bea496fac",
        "is_complete": true,
        "validation_results": {}
    },
    "rates": [
        {
            "object_id": "37ccdc9c210940cb8c554610207b553d",
            "object_created": "2024-06-25T21:41:46.129Z",
            "object_owner": "mrhippo@goshippo.com",
            "shipment": "06bee61d141545d08690631fbb27f602",
            "amount": "8.45",
            "currency": "USD",
            "amount_local": "8.45",
            "currency_local": "USD",
            "attributes": [
                "FASTEST",
                "CHEAPEST",
                "BESTVALUE"
            ],
            "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",
            "arrives_by": "2024-07-05",
            "duration_terms": "2 to 3 business days",
            "messages": [],
            "carrier_account": "425b61f50b3642948fb3afa8b3687581",
            "zone": null,
            "test": false,
            "servicelevel": {
                "name": "Ground Advantage",
                "token": "usps_ground_advantage",
                "terms": "",
                "extended_token": "usps_ground_advantage",
                "display_name": "Ground Advantage",
                "parent_servicelevel": null
            },
            "estimated_days": 3,
            "included_insurance_price": null
        }
    ],
    "alternate_address_to": null,
    "customs_declaration": null
}
```

Use the rate `object_id` associated with the new service level token that supports drop off in the [transactions endpoint](/api-reference/transactions/create-a-shipping-label) to purchase the label. In this example use the token `usps_ground_advantage`.

```shell Purchase label for drop off request theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "rate": "37ccdc9c210940cb8c554610207b553d",
  "async": false,
  "label_file_type": "PDF",
  "metadata": "usps_rate_qr_code_success"
}'
```

```json Purchase label for drop off response theme={null}
{
  "object_state": "VALID",
  "status": "SUCCESS",
  "object_created": "2024-06-25T21:42:19.048Z",
  "object_updated": "2024-06-25T21:42:24.926Z",
  "object_id": "c8b2789b5e66420186450167eeb761f9",
  "object_owner": "mrhippo@goshippo.com",
  "test": false,
  "rate": "37ccdc9c210940cb8c554610207b553d",
  "tracking_number": "92055901755477000000000015",
  "tracking_status": "PRE_TRANSIT",
  "eta": null,
  "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92055901755477000000000015",
  "label_url": "https://shippo-delivery-east.s3.amazonaws.com/c8b2789b5e66420186450167eeb761f9.pdf",
  "commercial_invoice_url": null,
  "messages": [],
  "order": null,
  "metadata": "usps_rate_qr_code_success",
  "parcel": "27a76dad79a84655add8eda8866b397e",
  "billing": {
    "payments": []
  },
  "qr_code_url": "https://shippo-delivery-east.s3.amazonaws.com/c8b2789b5e66420186450167eeb761f9_qr_code.png",
  "created_by": {
    "first_name": "Mr.",
    "last_name": "Hippo",
    "username": "mrhippo@goshippo.com"
  }
}
```

You can download and scan the scannable code `qr_code_url` at supporting drop off locations.

<Info>
  **Note**

  Your carrier will not always return a QR code. This may be because the carrier does not support that feature or because of other limitations.
</Info>

### Create a drop off Instalabel shipment

Use the following example to create an [Instalabel](/guides/single-call) for a drop off shipment.
Before creating an Instalabel, you must have your [carrier object ID](/shipments/rate-shopping-with-carriers#capture-carrier-object-id) and the [service level token](/api-reference/service-groups/list-all-service-groups) that supports drop off.

```shell Drop off Instalabel request theme={null}
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'\
--data-raw '{
  "shipment": {
    "address_from": {
            "name": "Mr. Hippo",
            "street1": "215 Clayton St.",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94117",
            "country": "US",
            "phone": "4151234567",
            "email": "mrhippo@goshippo.com",
            "is_residential": null
    },
    "address_to": {
      "name": "Mrs. Hippo",
      "street1": "1092 Indian Summer Ct",
      "city": "San Jose",
      "state": "CA",
      "zip": "95122",
      "country": "US",
      "phone": "4159876543",
      "email": "mrshippo@goshippo.com"
    },
    "parcels": [{
      "weight": "1",
      "length": "10",
      "width": "10",
      "height": "10",
      "distance_unit": "in",
      "mass_unit": "lb"
    }]
  },
  "carrier_account": "2c79a675977d459ca7b74e003ed97854",
  "servicelevel_token": "usps_ground_advantage"
}'
```

```json Drop off Instalabel response theme={null}
{
  "object_state": "VALID",
  "status": "SUCCESS",
  "object_created": "2024-06-25T21:42:19.048Z",
  "object_updated": "2024-06-25T21:42:24.926Z",
  "object_id": "c8b2789b5e66420186450167eeb761f9",
  "object_owner": "mrhippo@goshippo.com",
  "test": false,
  "rate": "37ccdc9c210940cb8c554610207b553d",
  "tracking_number": "92055901755477000000000015",
  "tracking_status": "PRE_TRANSIT",
  "eta": null,
  "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92055901755477000000000015",
  "label_url": "https://shippo-delivery-east.s3.amazonaws.com/c8b2789b5e66420dffdfsdfgfg167eeb761f9.pdf",
  "commercial_invoice_url": null,
  "messages": [],
  "order": null,
  "metadata": "usps_rate_qr_code_success",
  "parcel": "27a76dad79a84655add8eda8866b397e",
  "billing": {
    "payments": []
  },
  "qr_code_url": null,
  "created_by": {
    "first_name": "Mr.",
    "last_name": "Hippo",
    "username": "mrhippo@goshippo.com"
  }
}
```

## Pickup

A pickup refers to a carrier collecting a parcel from your designated location instead of you bringing the parcel to the carrier location.
To request a pickup, use the [pickup endpoint](/api-reference/pickups/create-a-pickup).

```shell Create a pickup request theme={null}
curl https://api.goshippo.com/pickups/  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"  \
-d '{
      "carrier_account":"6c51273296864869829b96a80fb13ea1",
      "location":{
              "building_location_type": "Other",
              "building_type": "suite",
              "instructions": "Behind screen door",
              "address": {
                      "name": "Mrs Hippo",
                      "company": "Hungry Hippos",
                      "street1": "965 Mission St #201",
                      "city": "San Francisco",
                      "state": "CA",
                      "zip": "95122",
                      "country": "US",
                      "phone": "+14159876543",
                      "email": "mrshippo@shippo.com"
                  }
      },
      "transactions": ["7439c279b374494c9a80ca24f59e6fc5"],
      "requested_start_time":"2024-05-12T12:00:00Z",
      "requested_end_time": "2024-05-12T16:00:00Z",
      "metadata": "Customer ID 123456",
      "is_test": false
    }'
```

```json Create a pickup response theme={null}
    {
  "carrier_account": "6c51273296864869829b96a80fb13ea1",
  "location": {
    "address": {
        "name": "Mrs Hippo",
        "company": "Hungry Hippos",
        "street1": "965 Mission St #201",
        "city": "San Francisco",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "+14159876543",
        "email": "mrshippo@shippo.com"
    },
    "building_location_type": "Other",
    "building_type": "suite",
    "instructions": "Behind screen door"
  },
  "metadata": "string",
  "requested_end_time": "2024-05-12T16:00:00Z",
  "requested_start_time": "2024-05-12T12:00:00Z",
  "transactions": [
    "7439c279b374494c9a80ca24f59e6fc5"
  ]
}

```


# Dry ice shipments
Source: https://docs.goshippo.com/shipments/dry-ice-shipment

Learn how to create shipping labels for dry ice shipments using the extras field in the Shippo Shipment object.

Shippo supports creating labels for shipping dry ice packed shipments by specifying options in the `extras` field of the Shipment object.

## Creating a dry ice shipment

To create a label for a shipment that will contain dry ice, you will need to specify options in the Shipment `extra` field.

cURL

```shell theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d address_from="d799c2679e644279b59fe661ac8fa488"\
    -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
    -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
    -d extra='{"dry_ice": {"contains_dry_ice": true, "weight": "0.1"}}'\
    -d async=false
```

In the response you'll get your usual Shipment object with all of the available rates for your dry ice shipment.

```json theme={null}
{
    "address_from": {
        "city": "San Francisco",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Mr Hippo",
        "object_id": "b631001acb534e2bbf7cea94adfd2d00",
        "phone": "4151234567",
        "state": "CA",
        "street1": "965 Mission St",
        "street2": "APT 572",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "94103"
    },
    "address_return": {
        "city": "San Francisco",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Mr Hippo",
        "object_id": "b631001acb534e2bbf7cea94adfd2d00",
        "phone": "4151234567",
        "state": "CA",
        "street1": "965 Mission St",
        "street2": "APT 572",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "94103"
    },
    "address_to": {
        "city": "Brooklyn",
        "company": "",
        "country": "US",
        "is_complete": false,
        "is_residential": null,
        "name": "Billy Bob",
        "object_id": "13d8b016de1c4befbdff900cd05ad2da",
        "phone": "4151234567",
        "state": "NY",
        "street1": "206 1ST ST",
        "street2": "STE 202",
        "street3": "",
        "street_no": "",
        "test": true,
        "validation_results": [],
        "zip": "11232"
    },
    "carrier_accounts": [
        "078870331023437cb917f5187429b093"
    ],
    "customs_declaration": null,
    "extra": {
        "dry_ice": {
            "contains_dry_ice": true,
            "weight": "0.1"
        }
    },
    "messages": [],
    "metadata": "",
    "object_created": "2017-08-03T17:54:54.006Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2017-08-03T17:54:54.006Z",
    "parcels": [
        {
            "distance_unit": "in",
            "extra": [],
            "height": "3.0000",
            "length": "10.0000",
            "line_items": [],
            "mass_unit": "lb",
            "metadata": "",
            "object_created": "2017-08-03T17:54:53.976Z",
            "object_id": "6fb5951a0900439b8770bc1814ee5528",
            "object_owner": "shippotle@shippo.com",
            "object_state": "VALID",
            "object_updated": "2017-08-03T17:54:54.024Z",
            "template": null,
            "test": true,
            "value_amount": null,
            "value_currency": null,
            "weight": "1.0000",
            "width": "3.0000"
        }
    ],
    "rates": [
        {
            "amount": "14.16",
            "amount_local": "14.16",
            "arrives_by": null,
            "attributes": [
                "BESTVALUE",
                "CHEAPEST",
                "FASTEST"
            ],
            "carrier_account": "078870331023437cb917f5187429b093",
            "currency": "USD",
            "currency_local": "USD",
            "duration_terms": "",
            "estimated_days": 5,
            "messages": [],
            "object_created": "2017-08-03T17:54:56.057Z",
            "object_id": "d870ae7efc7c45eabf097986d45d4f09",
            "object_owner": "shippotle@shippo.com",
            "provider": "FedEx",
            "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/FedEx.png",
            "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/FedEx.png",
            "servicelevel": {
                "name": "Ground",
                "terms": "",
                "token": "fedex_ground"
            },
            "shipment": "6781b0124d2d4f8cbdd24bd589c61460",
            "test": true,
            "zone": "8"
        }
    ],
    "shipment_date": "2017-08-03T17:54:53.975Z",
    "status": "SUCCESS"
}
```

## Create a dry ice shipment label

You can then use any rate `object_id` that was returned to create a transaction and get your shipping label:

cURL

```shell theme={null}
curl https://api.goshippo.com/transactions\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
```

Your transaction response will look the same as any other shipment:

```json theme={null}
{
    "commercial_invoice_url": null,
    "eta": null,
    "label_url": "https://shippo-delivery-east.s3.amazonaws.com/fe52964dbfe449efb6210f0caa9fdee8.pdf?Signature=aF9ujJ%2BOV5pJc24XoTuKeBmfJCQ%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "messages": [],
    "metadata": "",
    "object_created": "2017-08-03T17:55:44.347Z",
    "object_id": "fe52964dbfe449efb6210f0caa9fdee8",
    "object_owner": "shippotle@shippo.com",
    "object_state": "VALID",
    "object_updated": "2017-08-03T17:55:46.086Z",
    "order": null,
    "parcel": "6fb5951a0900439b8770bc1814ee5528",
    "rate": "d870ae7efc7c45eabf097986d45d4f09",
    "status": "SUCCESS",
    "test": false,
    "tracking_number": "794609767977",
    "tracking_status": "UNKNOWN",
    "tracking_url_provider": "https://www.fedex.com/apps/fedextrack/?action=track&cntry_code=us&trackingnumber=794609767977"
}
```

## Supported carriers & services

The following carriers services are supported for dry ice shipments.

**FedEx**

* Ground
* Express Saver
* 2 Day
* 2 Day A.M.
* Standard Overnight
* Priority Overnight
* First Overnight

**UPS**

All service levels support dry ice shipping.


# Hazardous or dangerous materials shipping
Source: https://docs.goshippo.com/shipments/hazmat

Declare hazardous materials like lithium batteries and biological items when creating shipments with the Shippo API.

## What are hazardous materials?

Hazardous materials are things that can cause harm to people. We commonly refer to these as hazmat or dangerous materials. These include things such as radioactive materials, lithium batteries, and biological materials. When shipping hazmat items, you must follow the carrier guidelines.
Follow this guide to learn about shipping hazmat items.

## How do I know if I am shipping hazardous materials?

USPS provides [guidelines for determining if a shipment contains hazardous materials](https://pe.usps.com/text/pub52/pub52c3_010.htm) that may impact how you ship. Review these guidelines to determine if they affect your shipment.

For domestic hazmat shipments, USPS only offer the ground service level USPS Ground Advantage.

## How do I declare that I am shipping hazardous materials?

If you have determined that you are shipping hazardous materials or the items you are shipping contain hazardous materials (for example, a mobile phone containing a lithium battery), you must declare when creating your shipment.
In your [Shipments object](/api-reference/shipments/list-all-shipments), create a `dangerous_goods` object in [shipments extra](/api-reference/shipments/list-all-shipments).

```json theme={null}
{
    "extra": { 
        "dangerous_goods": {
            "contains": true,
            "biological_material": {
                "contains": true
            },
            "lithium_batteries": {
                "contains": true
            }
        }
    }
}
```

For domestic (within the US) shipments, you must declare if your shipment contains any hazardous materials by setting `“contains”:true`

```json theme={null}
"dangerous_goods": {
	"contains": true
}
```

For domestic returns, you must set  `“contains”:true` in the `biological_material` object, if your shipment contains biological materials.

```json theme={null}
"dangerous_goods": {
	"biological_material": {
		"contains": true
	}
}
```

For international shipments, you must set `“contains”:true`, in the `lithium_batteries` object, if your shipment contains lithium batteries.

```json theme={null}
"dangerous_goods": {
	"lithium_batteries": {
		"contains": true
	}
}
```

<Info>
  **Note**

  Carefully review the USPS guidance on shipping lithium batteries internationally. Only “Class 9 - lithium batteries, unmarked package - New electronic devices installed or packaged with lithium batteries (no marking)" can be shipped internationally.
</Info>

The following example shows the creation of a shipment that contains dangerous goods.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d $'{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@shippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
    “extra”:
        {
        "dangerous_goods": {
            "contains": true,
            "lithium_batteries": {
                "contains": false
                },
            "biological_material": {
                "contains": false
                }
                }
            },

      "async": false
  }'

```

The generated shipping label contains a “H” to show the package contains hazardous materials. For example, this label for a domestic shipment containing hazardous materials.

<img alt="sample shipping label including hazmat details" />

## Hazardous materials returns

To learn about returns labels, follow our [Returns guide](/shipments/returns). To generate a pay-on-use return label for shipping hazardous materials, create a new Shipment object with a `dangerous_goods` object and set an `is_return` field as true inside the extra attribute.

<Info>
  The Shippo API swaps the original address\_to of the outbound transaction to the address\_from for the return label.
</Info>

The following example shows the creation of a shipment that contains dangerous goods including a returns label.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d $'{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@shippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
    “extra”:
        {
        "dangerous_goods": {
            "contains": true,
            "lithium_batteries": {
                "contains": false
                },
            "biological_material": {
                "contains": false
                }
                },
        "is_return": true
            },
      "async": false
  }'

```


# Multi-piece shipment
Source: https://docs.goshippo.com/shipments/multi-piece-shipment

Save on shipping by grouping multiple parcels going to the same destination into a single multi-piece shipment with Shippo.

Shipments with multiple parcels sent to the same destination can be grouped together in a multi-piece shipment to save money.

Multi-piece parcels in a single shipment may receive timeouts at certain thresholds depending on each carrier.

* Using UPS, you can request rates for up to 50 parcels in a single shipment. You can purchase labels for up to 40 parcels in a [single shipment](#create-a-multi-piece-shipment). Additionally, you can purchase labels for up to 200 parcels in a single shipment using an [extended multi-piece shipment](#create-an-extended-multi-piece-shipment).
* Using FedEx, sending more than 12 parcels within one shipment may result in a timeout.
* USPS does not support multi-piece parcels in a single shipment at this time.

### Create a multi-piece shipment

To create a multi-piece shipment, add a list of Parcel objects to the `parcels` field in a Shipment. Generating rates and creating transactions works the exact same way as with normal shipments. The limit on the number of parcels depends on each carrier's restrictions.

<Info>
  **Note**

  For more than 40 labels in a single shipment, create an [extended multi-piece shipment](#create-an-extended-multi-piece-shipment).
</Info>

The Shipment request content should look like:

**Request:**

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_Token>"\
      -H "Content-Type: application/json"\
      -d '{
              "address_from": {
                  "name": "Mr. Hippo",
                  "street1": "215 Clayton St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94117",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "address_to": {
                  "name": "Mrs. Hippo",
                  "street1": "965 Mission St.",
                  "city": "San Francisco",
                  "state": "CA",
                  "zip": "94105",
                  "country": "US",
                  "phone": "+1 555 341 9393",
                  "email": "support@shippo.com"
              },
              "parcels": [
                  {
                      "length": "5",
                      "width": "5",
                      "height": "5",
                      "distance_unit": "in",
                      "weight": "2",
                      "mass_unit": "lb"
                  },
                  {
                      "length": "10",
                      "width": "10",
                      "height": "10",
                      "distance_unit": "in",
                      "weight": "2",
                      "mass_unit": "lb"
                  }
              ],
              "async": false
          }'
  ```

  ```Python {% title="Python" %} theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  address_from = components.AddressCreateRequest(
      name="Shawn Ippotle",
      street1="215 Clayton St.",
      city="San Francisco",
      state="CA",
      zip="94117",
      country="US",
      phone="+1 555 341 9393",
      email="shippotle@shippo.com"
  )

  address_to = components.AddressCreateRequest(
      name="Mr Hippo",
      street1="Broadway 1",
      city="New York",
      state="NY",
      zip="10007",
      country="US",
      phone="+1 555 341 9393",
      email="mrhippo@shippo.com",
  )

  parcel_1 = components.ParcelCreateRequest(
      length="5",
      width="5",
      height="5",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  parcel_2 = components.ParcelCreateRequest(
      length="10",
      width="10",
      height="10",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  shipment = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          parcels=[parcel_1, parcel_2]
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'shippotle@shippo.com'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'street1' => 'Broadway 1',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'mrhippo@shippo.com'
  );

  $parcel_1 = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $parcel_2 = array(
      'length'=> '10',
      'width'=> '10',
      'height'=> '10',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $shipment = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "parcels" => array($parcel_1, $parcel_2),
          "async" => false
      )
  );
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>'});

  const addressFrom: AddressCreateRequest  = {
      name: "Shawn Ippotle",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com"
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      street1: "Broadway 1",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
      phone: "+1 555 341 9393",
      email: "mrhippo@shippo.com"
  };

  const parcel1: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const parcel2: ParcelCreateRequest = {
      length: "10",
      width: "10",
      height: "10",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const shipment = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel1, parcel2],
      async: false
  });
  ```

  ```Java {% title="Java" %} theme={null}
  Shippo.setApiKey('<API_Token>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");
  addressToMap.put("phone", "+1 555 341 9393");
  addressToMap.put("email", "mrhippo@goshipppo.com");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");
  addressFromMap.put("email", "mshippo@goshipppo.com");
  addressFromMap.put("phone", "+1 619 231 1515");
  addressFromMap.put("metadata", "Customer ID 123456");

  List<HashMap> parcelList = new List();
  // Parcel One
  HashMap<String, Object> parcelMapOne = new HashMap<String, Object>();
  parcelMapOne.put("length", "5");
  parcelMapOne.put("width", "5");
  parcelMapOne.put("height", "5");
  parcelMapOne.put("distance_unit", "in");
  parcelMapOne.put("weight", "2");
  parcelMapOne.put("mass_unit", "lb");

  // Parcel Two
  HashMap<String, Object> parcelMapTwo = new HashMap<String, Object>();
  parcelMapTwo.put("length", "1");
  parcelMapTwo.put("width", "1");
  parcelMapTwo.put("height", "1");
  parcelMapTwo.put("distance_unit", "in");
  parcelMapTwo.put("weight", "2");
  parcelMapTwo.put("mass_unit", "lb");

  parcelList.add(parcelMapOne);
  parcelList.add(parcelMapTwo);

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelList);
  shipmentMap.put("async", false);
  ```

  ```cs C# {% title="C#" %} theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_TOKEN>");
  AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Mr Hippo",
          Street1 = "Broadway 1",
          City = "New York",
          State = "NY",
          Zip = "10007",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "mrhippo@shippo.com",
      }
  );
  Shippo.Models.Components.Parcels parcel1 = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "5",
          Width = "5",
          Height = "5",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  Shippo.Models.Components.Parcels parcel2 = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "10",
          Width = "10",
          Height = "10",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  Shipment shipment = await sdk.Shipments.CreateAsync(
      shipmentCreateRequest: new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel1, parcel2 },
      }
  );
  ```
</CodeGroup>

As usual, the Shipment request will return a list of Rates for you to select from. The Rate `amount` refers to the cost of the entire Shipment with multiple parcel, not per parcel.

**Response:**

```json theme={null}
{
    "status": "SUCCESS",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@shippo.com",
    "address_from": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "address_to": {
        "object_id": "4c7185d353764d0985a6a7825aed8ffb",
        "validation_results": {},
        "is_complete": true,
        "name":"Mrs. Hippo",
        "street1":"965 Mission St.",
        "city":"San Francisco",
        "state":"CA",
        "zip":"94105",
        "country":"US",
        "phone":"+1 555 341 9393",
        "email":"support@shippo.com",
        "is_residential": false
    },
    "address_return": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "parcels": [
        {
            "object_id": "ec952343dd4843c39b42aca620471fd5",
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_updated": "2013-12-01T06:24:21.121Z",
            "object_owner": "shippotle@shippo.com",
            "template": null,
            "length":"5",
            "width":"5",
            "height":"5",
            "distance_unit":"in",
            "weight":"2",
            "mass_unit":"lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        },
        {
            "object_id": "dbe0260bb2674c709fa45667cf353f27",
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_updated": "2013-12-01T06:24:21.121Z",
            "object_owner": "shippotle@shippo.com",
            "template": null,
            "length":"5",
            "width":"5",
            "height":"5",
            "distance_unit":"in",
            "weight":"2",
            "mass_unit":"lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2013-12-03T12:00:00.000Z",
    "extra": {
        "insurance": {
            "amount": "",
            "currency": ""
        },
        "reference_1": "",
        "reference_2": ""
    },
    "customs_declaration": "",
    "rates": [
        {
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@shippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "65.80",
            "currency": "USD",
            "amount_local": "65.80",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
                "name": "Ground",
                "token": "fedex_ground",
                "terms": ""
            },
            "days": 5,
            "arrives_by": null,
            "duration_terms": null,
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": []
}
```

### Create an extended multi-piece shipment

UPS supports up to 200 parcels in a single shipment.

* For 40 parcels or less, in a single shipment, you can choose to [create a multi-piece shipment](#create-a-multi-piece-shipment).
* For more than 40, you must create an extended multi-piece shipment.

Extended multi-piece shipments require an [Instalabel](/guides/single-call) where you purchase a label without generating a rate.

<Info>
  **note**

  Currently, Instalabel is not available for [Shippo FedEx and UPS accounts](/carriers/carrier-accounts#connecting-shippo-carrier-accounts). If you want use either FedEx or UPS for Instalabel purchases, you must use [your own carrier account](/carriers/carrier-accounts#connecting-your-own-carrier-account).
</Info>

In addition to your shipment details, the following are required to create an Instalabel for a multi-piece shipment.

1. Your chosen [carrier account ID](/shipments/rate-shopping-with-carriers#capture-carrier-object-id).
2. Your chosen [service level token](/api-reference/service-groups/list-all-service-groups).
3. Set `async` to `true`.

The following examples show an [Instalabel call](/api-reference/transactions/create-a-shipping-label) for a multi-piece shipment.

```shell cURL theme={null}
curl https://api.goshippo.com/transactions/  \
    -H "Authorization: ShippoToken <API_Token>" \
    -H "Content-Type: application/json"  \
    -d '{
        "shipment": {
            "address_from": {
                "name": "Mr. Hippo",
                "street1": "215 Clayton St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94117",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@shippo.com"
            },
            "address_to": {
                "name": "Mrs. Hippo",
                "street1": "965 Mission St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94105",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@shippo.com"
            },
           "parcels": [
                {
                    "length": "5",
                    "width": "5",
                    "height": "5",
                    "distance_unit": "in",
                    "weight": "2",
                    "mass_unit": "lb"
                },
                {
                    "length": "10",
                    "width": "10",
                    "height": "10",
                    "distance_unit": "in",
                    "weight": "2",
                    "mass_unit": "lb"
                },
                {
                    "length": "5",
                    "width": "10",
                    "height": "2",
                    "distance_unit": "in",
                    "weight": "2",
                    "mass_unit": "lb"
                }
            ],
        },
        "carrier_account": "b741b99f95e841639b54272834bc478c",
        "servicelevel_token": "ups_ground",
        "async":true
        }'
```

## How to retrieve labels for each parcel

You can purchase a multi-piece shipping rate by POSTing the Rate `object_id` to the Transaction endpoint as usual. A separate transaction will be created for each parcel.

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/transactions\
      -H "Authorization: ShippoToken <API_Token>"\
      -d rate="cf6fea899f1848b494d9568e8266e076"
      -d label_file_type="PDF"
      -d async=false
  ```

  ```Python {% title="Python" %} theme={null}
  # Get the first rate in the rates results.
  # Customize this based on your business logic.
  rate = shipment.rates[0]

  # Purchase the desired rate. 
  transaction = shippo_sdk.transactions.create(
      components.TransactionCreateRequest(
          rate=rate.object_id,
          label_file_type=components.LabelFileTypeEnum.PDF
      )
  )

  # Retrieve label url and tracking number or error message
  if transaction.status == "SUCCESS":
      print(transaction.label_url)
      print(transaction.tracking_number)
  else:
      print(transaction.messages)
  ```

  ```PHP {% title="PHP" %} theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  $rate = $shipment["rates"][0];

  // Purchase the desired rate.
  $transaction = Shippo_Transaction::create( array( 
      'rate' => $rate["object_id"], 
      'label_file_type' => "PDF", 
      'async' => false ) );

  // Retrieve label url and tracking number or error message
  if ($transaction["status"] == "SUCCESS"){
      echo( $transaction["label_url"] );
      echo("\n");
      echo( $transaction["tracking_number"] );
  }else {
      echo( $transaction["messages"] );
  }
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.
  const rate = shipment.rates[0];

  // Purchase the desired rate.
  const transaction = await shippo.transactions.create({
      rate: rate?.objectId,
      labelFileType: LabelFileTypeEnum.Pdf,
      async: false
  });

  // Retrieve label url and tracking number or error message
  if (transaction.status == TransactionStatusEnum.Success) {
      console.log(transaction.labelUrl)
      console.log(transaction.trackingNumber)
  } else {
      console.log(transaction.messages)
  }
  ```

  ```Java {% title="Java" %} theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your own business logic
  Rate rate = shipment.ratesList[0];

  HashMap<String, Object> transactionMap = new HashMap<String, Object>();
  transactionMap.put("rate", rate.objectId);
  transactionMap.put("async", false);

  // Purchase the desired rate
  Transaction transaction = Transaction.create(transactionParameters);

  if (transaction.getStatus().equals("SUCCESS")) {
  	System.out.println(String.format("Label url : %s",
  	 transaction.getLabelUrl()));
  	System.out.println(String.format("Tracking number : %s",
  	 transaction.getTrackingNumber()));
  } else {
  	System.out.println(String.format("An Error has occured while generating your label. Messages : %s",
  	 transaction.getMessages()));
  }
  ```

  ```cs C# {% title="C#" %} theme={null}
  // Get the first rate in the rates results.
  // Customize this based on your business logic.        
  Rate rate = shipment.Rates[0];
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateTransactionCreateRequest(
          new TransactionCreateRequest()
          {
              Rate = rate.ObjectId,
              LabelFileType = LabelFileTypeEnum.Pdf,
          }
      )
  );
  if (transaction.Status == TransactionStatusEnum.Success)
  {
      Console.WriteLine($"{transaction.LabelUrl}");
      Console.WriteLine($"{transaction.TrackingNumber}");
  }
  else
  {
      Console.WriteLine($"{transaction.Messages}");
  }
  ```
</CodeGroup>

You can also create multi-piece shipments in one API call. Check out our [tutorial for single label call creation](/guides/single-call) for more details.

The POST request returns the primary Transaction object in the response. To get labels for all the parcels in the Shipment you need to filter for each parcel transaction.

1. The Transaction response after you've purchased the rate provides you with the primary `tracking_number`of the entire Shipment and the `label_url` for the first parcel of the Shipment.
   As an example, [this label](https://shippo-static.s3.amazonaws.com/img/illustrations/mps1.png) has the primary tracking number on it incl. information about the status of the entire multi-piece shipment.
2. To retrieve labels for the rest of the parcels in the Shipment, you need to make another GET request to the Transaction endpoint with the Rate `object_id` as the query parameter.
   [These sample labels](https://shippo-static.s3.amazonaws.com/img/illustrations/mps2.png) have both the primary tracking number (`MSTR`) on it as well as their own parcel-specific tracking number.

Here's an example request:

**Request:**

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/transactions/?rate=cf6fea899f1848b494d9568e8266e076\
  -H "Authorization: ShippoToken <API_Token>"
  ```

  ```Python {% title="Python" %} theme={null}
  import shippo
  from shippo.models import operations

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  transactions = shippo_sdk.transactions.list(
      operations.ListTransactionsRequest(rate='cf6fea899f1848b494d9568e8266e076')
  )

  ```

  ```PHP {% title="PHP" %} theme={null}
  require_once('lib/Shippo.php');

  Shippo::setApiKey("<API_Token>");

  $transactions = Shippo_Transaction::all( array('rate' => 'cf6fea899f1848b494d9568e8266e076'));
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const transactions = await shippo.transactions.list({
      rate: "cf6fea899f1848b494d9568e8266e076"
  });
  ```
</CodeGroup>

The API will respond with a JSON serialized list of the transactions that belong to this Rate. Each of these transactions belongs to exactly one parcel of the multi-piece shipment. Each transaction has a unique `tracking_number` and `label_url` field for it's associated parcel.

**Response:**

```json theme={null}
{
   "count":5,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"shippotle@shippo.com",
         "was_test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":{
            "object_created":"2014-07-17T00:43:50.402Z",
            "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
            "status":"UNKNOWN",
            "status_details":"",
            "status_date":null
         },
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "eta":"2014-07-21T12:00:00.000Z",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "commercial_invoice_url": "",
         "messages":[

         ],
         "metadata":""
      },
      {...},
      {...}
   ]
}
```

If you have more than 5 transactions that belong to the Rate, the response will be paginated.

You can modify your request to increase the number of transactions per page.

Example:

```json theme={null}
https://api.goshippo.com/transactions/?results=10&rate=ee81fab0372e419ab52245c8952ccaeb
```

Or you can retrieve each page of the response listed in the 'next' parameter.

Example:

```json theme={null}
"next": https://api.goshippo.com/transactions/?rate=ee81fab0372e419ab52245c8952ccaeb&page=2
```

## Multi-piece shipping label references

Some carriers support adding your own reference to a shipping label. For more information about support for multi-piece label reference support, review our [Carrier reference fields](/carriers/carrier-reference-fields#add-reference-details-to-a-parcel) guide.

## Parcel-level insurance

You can also purchase insurance for each parcel of the multi-piece shipment. This can be done through the [extras](/api-reference/parcels/list-all-parcels) attribute when creating your Parcel object within the Shipment request. Here is a sample request for a Shipment with different insurance amounts for each Parcel.

```shell cURL theme={null}
curl https://api.goshippo.com/shipment/\
-H "Authorization: ShippoToken <API_Token>"\
-H "Content-Type: application/json"\
-d '{
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "address_to": "42236bcf36214f62bcc6d7f12f02a849",
    "parcels": [
        {
            "length": "5",
            "width": "5",
            "height": "5",
            "distance_unit": "cm",
            "weight": "2",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box1",
            "extra": {
                "insurance": {
                    "amount": 25.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "5",
            "width": "10",
            "height": "15",
            "distance_unit": "cm",
            "weight": "6",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box2",
            "extra": {
                "insurance": {
                    "amount": 50.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "2",
            "width": "8",
            "height": "9",
            "distance_unit": "cm",
            "weight": "5",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box3",
            "extra": {
                "insurance": {
                    "amount": 45.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        }
    ],
    "async": false
}
```

### Handling shipment-level and parcel-level insurance

* If both shipment-level and parcel-level insurance are specified, the parcel-level insurance will take precedence. Parcels without parcel-level insurance will have the shipment-level insurance amount applied to that parcel.
* If only shipment-level insurance is specified, then the shipment insurance amount will be applied to *each parcel* -- not divide amongst parcels.

## Parcel-level Collect on Delivery

UPS offer Collect on Delivery (COD) for individual parcels in a multi-piece shipment. You can specific your COD preference in the [extras](/api-reference/parcels/list-all-parcels) attribute of the Parcel object when creating your Shipment.


# QR codes
Source: https://docs.goshippo.com/shipments/qr-code

Generate QR codes for printerless shipping with USPS, Royal Mail, and Evri so merchants can print labels at drop-off.

QR codes can be used by merchants to print labels at in-store locations. This is a useful feature for merchants who do not have access to printing facilities.
Merchants bring their prepackaged shipment to a supported location and redeem their shipping label by scanning a digital QR code on their mobile device.

Currently, Shippo supports QR code generation for USPS, Royal Mail and Evri.

## USPS compliance

To comply with USPS requirements, QR codes should be generated on behalf of merchants and sellers who intend to use them.
Ideally merchants or sellers will be able to “opt-in” to automatically receive QR codes when creating labels.
This approach will 1) ensure a high adoption rate (with QR codes being scanned for in-store label printing) and 2) help reduce costs and maintenance related to QR code generation within USPS label broker systems.

All Shippo API users and third party integrators are subject to the Label Broker terms and conditions below:
[https://www.usps.com/terms-conditions/label-broker.htm](https://www.usps.com/terms-conditions/label-broker.htm)

## Create a QR code

To create a QR code for printerless shipping, you will need to

1. make sure the merchant requests it and
2. specify `qr_code_requested `as the Shipment extra field

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" \
    -d address_to="42236bcf36214f62bcc6d7f12f02a849" \
    -d parcels=["defeb0a3a84949d390c94159ceb39bc6"] \
    -d extra='{"qr_code_requested": true}' \
    -d async=false
```

In the response you’ll get your usual Shipment object with all of the available rates. You can then use any rate `object_id` that was returned to create a transaction and get your shipping label and QR code:

```shell cURL theme={null}
curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PNG"
    -d async=false
```

The Transaction API provides a `qr_code_url` as a response if the Shipment has a `qr_code_requested` flag and the carrier provides such an option.

```json theme={null}
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-23T18:26:07.753Z",
   "object_updated": "2022-11-23T18:26:13.472Z",
   "object_id": "1cb8f204c01044d8b80ebffe9e8ada7c",
   "object_owner": "shippotle@shippo.com",
   "test": true,
   "rate": "3f7479c81fbd44dea767ad7569b0a5e9",
   "tracking_number": "92055901755477000000000015",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92055901755477000000000015",
   "label_url": "https://shippo-delivery-east.s3.amazonaws.com/1cb8f204c01044d8b80ebffe9e8ada7c.png?Signature=r609rRqZbsiV%2Fy2mQG4CMHbsSnI%3D&Expires=1700763970&AWSAccessKeyId=AKIAJKHBTIO2YQPYZSEA&versionId=Xw8i1.ut9lrHOKonttu2lwV67NnA7uka",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "defeb0a3a84949d390c94159ceb39bc6",
   "billing": {
       "payments": []
   },
   "qr_code_url": "https://shippo-delivery-east.s3.amazonaws.com/1cb8f204c01044d8b80ebffe9e8ada7c_qr_code.png?Signature=EMf5A3hYzUi1t35tkgha1rCRnXY%3D&Expires=1700763973&AWSAccessKeyId=AKIAJKHBTIO2YQPYZSEA&versionId=Qhg_FflYWTHkLQeBaxMSaCuJ7zx3gALr"
}
```

It's important to share instructions along with the QR code with details of how to use it.
This incudes some of the following items.

* Detail on how to find a supporting in-store location such as the Post Office.
* Details about the packing required. Normally, merchants items should be already packaged and ready-to-ship.

## Sample QR code instructions

```
[Friendly introduction (e.g.: Hi first name)]

[Merchant info about outbound shipment here (e.g.: items, order #, RMA #, date, etc.]

For your convenience, you can print your outbound label at participating USPS® Post Offices®. Simply bring your packaged and ready-to-ship item and show the Label Broker code below to the USPS Retail Associate at the Retail Counter.

<img src="/images/Shipments/qr-code.png" alt="QR code sample" width="300" />

You can find participating locations here: [https://www.usps.com/business/label-broker.htm](https://www.usps.com/business/label-broker.htm)

You can also use this website for instructions on how to print your label at home.

```


# Rate shopping with carriers
Source: https://docs.goshippo.com/shipments/rate-shopping-with-carriers

Compare shipping rates from multiple carriers in a single API call to find the best price and service for your shipment.

## What is rate shopping?

Rates are the cost and service levels associated with a shipment. When you want to find the best cost and service level for a shipment, you can request rates from a number of different carriers in a single call. You can then compare the results to find the option that works best for your shipment. This practice is known as rate shopping.
When you create a Shipment object, rates are automatically generated for all carriers connected with your account. This can lead to a large number of rates returned for a shipment.

Follow this guide to learn how to rate shop for a specific subset of your available carriers.

## Rate shopping for specific carriers

### Capture carrier object ID

Capture the necessary carrier account object IDs. In this example, `6aa34d5f6865448fbb1ee93636e98999` and `7bb1235sdsd9sds6989845497874879`.

```shell cURL theme={null}
curl https://api.goshippo.com/carrier_accounts \
 -H "Authorization: ShippoToken <API_TOKEN>"
```

The expected response will look like this.

```json theme={null}
{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
    {
      "account_id": "****",
      "active": true,
      "carrier": "UPS",
      "parameters": {
        "account_number": "94567e",
        ….
      },
      "is_shippo_account": false,
      "metadata": "string",
      "object_id": "6aa34d5f6865448fbb1ee93636e98999",
      "object_owner": "bob+22@gmail.com",
      "test": false
    },
 {
      "account_id": "****",
      "active": true,
      "carrier": "USPS",
      "parameters": {
        "account_number": "9090a",
        ….
      },
      "is_shippo_account": false,
      "metadata": "string",
      "object_id": "7bb1235sdsd9sds6989845497874879",
      "object_owner": "bob+22@gmail.com",
      "test": false
    }

  ]
}
```

### Get rates

To get rates for specific carriers, create a Shipment and specify the carriers to be used using `carrier_accounts` field in the `/shipments` POST request to get rates as you usually would.

<img alt="" />

<img alt="" />

```json theme={null}
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@shippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
      "async": false,
    "carrier_accounts": [
        "6aa34d5f6865448fbb1ee93636e98999",
        "7bb1235sdsd9sds6989845497874879",
        ...
    ]

  }'
```

The expected response will include a list of Rates generated from only the carriers specified in `carrier_accounts` array.


# Returns
Source: https://docs.goshippo.com/shipments/returns

Generate scan-based return labels for USPS, FedEx, and UPS, and set custom return addresses using the Shippo API.

Setup your reverse-logistics and returns easily through the API.

1. [Scan-based return labels](#generate-a-return-label): These labels are free to print. You won't get charged unless it gets used. It's a great option if you want to add return labels to all your outbound packages. All Shippo return labels are scan-based, available for USPS, FedEx, and UPS shipments only. At the moment, you can only generate return labels for the same carrier that your outbound shipment was sent with
2. [Return address](#return-address): For failed deliveries or return shipments, you can specify a different return address than the initial outbound location

## Generate a return label

### Returns for USPS, FedEx, and UPS

To generate a pay-on-use return label, create a new Shipment object and set an `is_return` field as `true` inside the extra attribute.

<Info>
  **Note**

  For USPS, FedEx, and UPS, do not swap the addresses yourself -- the Shippo API will take care of this for you. This means that the original `address_to` of the outbound transaction becomes the `address_from` for the return label.
</Info>

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/shipments/ \
      -H "Authorization: ShippoToken <API_Token>" \
      -H "Content-Type: application/json" \
      -d '{
          "address_from": {
              "name": "Mr. Hippo",
              "street1": "215 Clayton St.",
              "city": "San Francisco",
              "state": "CA",
              "zip": "94117",
              "country": "US",
              "metadata": "merchant address"
          },
          "address_to": {
              "name": "Mrs. Hippo",
              "street1": "965 Mission St.",
              "city": "San Francisco",
              "state": "CA",
              "zip": "94105",
              "country": "US",
              "metadata": "customer address"
          },
          "parcels": ["7df2ecf8b4224763ab7c71fae7ec8274"],
          "shipment_date": "2023-12-03T12:00:00.000Z",
          "extra": { "is_return": true },
          "async": false
      }'
  ```

  ```Python {% title="Python" %} theme={null}
  # Create address_from, address_to and parcel variables first
  shipment_return = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          parcels=[parcel],
          extra=components.ShipmentExtra(
              is_return=True
          ),
          async_=False
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  // Create $fromAddress, $toAddress and $parcel variables first
  $shipment_return = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "parcels" => array($parcel),
          "extra" => array("is_return" => true),
          "async" => false
      )
  );
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  // Create addressFrom, addressTo and parcel variables first
  const shipmentReturn = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
      extra: {
          isReturn: true
      },
      async: false
  });
  ```

  ```Java {% title="Java" %} theme={null}
  HashMap<String, Object> returnShipmentMap = new HashMap<String, Object>();
  returnShipmentMap.put("address_from", addressFromMap);
  returnShipmentMap.put("address_to", addressToMap);
  returnShipmentMap.put("parcels", parcelMap);
  HashMap<String, Object> extraMap = new HashMap<String, Object>();
  extraMap.put("is_return", true);
  returnShipmentMap.put("extra", extraMap);
  returnShipmentMap.put("async", false);

  Shipment.create(returnShipmentMap);
  ```

  ```cs C# {% title="C#" %} theme={null}
  Shipment shipmentReturn = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
          Extra = new ShipmentExtra()
          {
              IsReturn = true
          },
          Async = false,
      }
  );
  ```
</CodeGroup>

After creating the Shipment, follow the [normal process of retrieving rates](/guides/generate-shipping-label) to select the service level that you'd like to use for the return, and proceed to create your return label.

When the return label is generated, it will be valid for a period of time. After this time, carriers may still accept these labels but it can cause the shipment to be flagged, returned, or destroyed without being eligible for a refund. Depending on your carrier, generated return labels are valid for different periods of time.

| Carrier | Return label validity |
| ------- | --------------------- |
| USPS    | 1 year                |
| FedEx   | 2 years               |
| UPS     | 100 days              |

### Returns for other carriers

If you need to generate a label for return shipments for carriers other than USPS, FedEx, and UPS, you can create a normal shipping label just with the addresses swapped.

However, normal shipping labels have a limited shipping window and the label may be rejected after that, so we do not recommend inserting them into your outbound package. Instead, you can provide a method for customers to contact your support services, and you can provide them with the link to the label.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/ \
    -H "Authorization: ShippoToken <API_Token>" \
    -H "Content-Type: application/json" \
    -d '{
        "address_from": {
            "name": "Mrs. Hippo",
            "street1": "965 Mission St.",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US",
            "metadata": "customer address"
        },
        "address_to": {
            "name": "Mr. Hippo",
            "street1": "215 Clayton St.",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94117",
            "country": "US",
            "metadata": "merchant address"
        },
        "parcels": ["7df2ecf8b4224763ab7c71fae7ec8274"],
        "shipment_date": "2023-12-03T12:00:00.000Z",
        "async": false
    }'
```

## Return Address

When creating an outbound Shipment for USPS, FedEx and UPS, you can specify a `address_return` that's different from your original shipping address (`address_from`). This can be useful if you want returned shipments to go back to a different place. For instance:

1. Failed deliveries: the Shipment will be returned to a different facility than the original outbound destination.
2. Scan-based labels: the Shippo API automatically swaps the `address_from` and `address_to` during the return label creation process. You can pass any address `object_id` or nested object in the corresponding fields -- they don't need to match the outbound addresses.

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_Token>"\
      -d address_from="d799c2679e644279b59fe661ac8fa488"\
      -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
      -d address_return="1d3tb2c51chj77ci27b7dfne3fibp264"\
      -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
      -d shipment_date="2023-12-03T12:00:00.000Z"\
      -d async=false
  ```

  ```Python {% title="Python" %} theme={null}
  # Create address_from, address_to, address_return and parcel variables first
  shipment_return = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          address_return=address_return,
          parcels=[parcel],
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  // Create $fromAddress, $toAddress, $returnAddress and $parcel variables first
  $shipment_return = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "address_return" => $returnAddress,
          "parcels" => array($parcel),
          "async" => false
      )
  );
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  // Create addressFrom, addressTo, addressReturn and parcel variables first
  const shipmentReturn = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      addressReturn: addressReturn,
      parcels: [parcel],
      async: false
  });
  ```

  ```Java {% title="Java" %} theme={null}
  HashMap<String, Object> returnShipmentMap = new HashMap<String, Object>();
  returnShipmentMap.put("address_from", addressFromMap);
  returnShipmentMap.put("address_to", addressToMap);
  returnShipmentMap.put("address_return", addressReturnMap);
  returnShipmentMap.put("parcels", parcelMap);
  returnShipmentMap.put("async", false);

  Shipment.create(returnShipmentMap);
  ```

  ```cs C# {% title="C#" %} theme={null}
  // Create addressFrom, addressTo, addressReturn and parcel variables first
  Shipment shipmentReturn = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          AddressReturn = addressReturn,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
          Async = false,
      }
  );
  ```
</CodeGroup>


# Saturday delivery
Source: https://docs.goshippo.com/shipments/saturday-delivery

Learn how to request Saturday delivery shipping rates by setting the saturday_delivery option in your Shippo shipment.

Some carriers offer the option to deliver packages to customers on Saturdays. To get shipping rates for Saturday deliveries, create a Shipment and set `saturday_delivery: true` in [Shipments Extras](/api-reference/shipments/list-all-shipments).

<Info>
  **info**

  By setting `saturday_delivery: true`, only saturday delivery options are returned. This means shipment options for other days are not returned.

  If you need shipment options for week days and Saturdays, create two Shipments. One with  `saturday_delivery:true` in `extra` and one without.
</Info>

The following example shows a request for a Saturday delivery Shipment.

**Request:**

```shell Saturday Shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
        "name": "Mr Hippo",
        "street1": "965 Mission Street",
        "street2": "Suite 480",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com"
  },
  "address_to": {
      "name": "Mr Hippo",
      "street1": "2967 Filbert Dr",
      "street2": "APT 3",
      "city": "Walnut Creek",
      "state": "CA",
      "zip": "94598",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com"
  },
  "parcels": [{
    "weight": "8",
    "length": "9",
    "width": "3",
    "height": "8",
    "distance_unit": "in",
    "mass_unit": "lb"
  }],
  "extra": {
    "saturday_delivery": "true"
  },
  "async": false
}'
```

**Response:**

```json Saturday Shipment response  theme={null}
{
    "carrier_accounts": [],
    "object_created": "2024-04-15T12:15:00.500Z",
    "object_updated": "2024-04-15T12:15:00.688Z",
    "object_id": "09f2f253f1bd42418bb586aea7be74cf",
    "object_owner": "mrhippo@goshippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "75318fbe88084e2abeba8acd41886ffc",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission Street",
        "validation_results": {},
        "street2": "Suite 480",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "3f7b80dd96524adc807ac6f579fc4359",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "2967 Filbert Dr",
        "validation_results": {},
        "street2": "APT 3",
        "street3": "",
        "city": "Walnut Creek",
        "state": "CA",
        "zip": "94598",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2024-04-15T12:15:00.473Z",
            "object_updated": "2024-04-15T12:15:00.506Z",
            "object_id": "cc7df8872e694ab38a6604fb72bf2e28",
            "object_owner": "adrian.collins@goshippo.com",
            "template": null,
            "extra": {},
            "length": "9.0000",
            "width": "8.0000",
            "height": "3.0000",
            "distance_unit": "in",
            "weight": "8.0000",
            "mass_unit": "lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2024-04-15T12:15:00.688Z",
    "address_return": {
        "object_id": "75318fbe88084e2abeba8acd41886ffc",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission Street",
        "validation_results": {},
        "street2": "Suite 480",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@goshippo.com",
        "is_residential": null,
        "test": true
    },
    "customs_declaration": null,
    "extra": {
        "saturday_delivery": "true"
    },
    "rates": [
        {
            "object_created": "2024-04-15T12:15:01.400Z",
            "object_id": "7cfebbe9de6b4c3dbef3b2ccd9754032",
            "object_owner": "adrian.collins@goshippo.com",
            "shipment": "09f2f253f1bd42418bb586aea7be74cf",
            "attributes": [],
            "amount": "20.32",
            "currency": "USD",
            "amount_local": "20.32",
            "currency_local": "USD",
            "provider": "DHL eCommerce",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/DHL_ecommerce.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/DHL_ecommerce.png",
            "servicelevel": {
                "name": "Parcels Expedited",
                "token": "dhl_ecommerce_parcels_expedited",
                "terms": ""
            },
            "estimated_days": 4,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "73fe2e0731eb4e4ca6fc68e1bb1291a4",
            "test": true,
            "zone": "USPS08"
        }
    ],
    "metadata": "",
    "test": true,
    "order": null
}
```


# Create a shipment
Source: https://docs.goshippo.com/shipments/shipments

Learn how to create a Shipment object in the Shippo API to automatically retrieve available shipping rates.

In the Shippo API, creating a [Shipment object](/api-reference/shipments/list-all-shipments) will automatically retrieve a list available rates.\
To create a Shipment object, call the shipment endpoint `https://api.goshippo.com/shipments/`.
At a minimum, a shipment requires a `address_from`, `address_to`, and `parcels`.

To learn how to create a Shipment object, follow [our guide](/guides/generate-shipping-label#create-a-shipment-object).

<Warning>
  Shipment objects and their associated rates are only retrievable for up to 390 days after creation.
</Warning>


# Shipping insurance
Source: https://docs.goshippo.com/shipments/shipping-insurance

Add shipping insurance to your shipments through Shippo's built-in coverage or directly from FedEx, UPS, and Ontrac.

You can use the Shippo API  to add insurance to your shipments programmatically. Shipping insurance helps you avoid losing money on lost or stolen packages.
The Shippo API supports two methods for purchasing insurance for your shipment.

<img alt="step 1 icon" /> You can purchase insurance using our [built-in insurance service](#insurance-for-single-package-shipments-using-xcover) powered by [XCover](https://www.xcover.com/en-us/help/partners/shippo). This is available for **ALL** of our carriers.

<img alt="step 2 icon" /> You can purchase insurance [directly from carriers](#insurance-for-single-package-shipments-using-carrier-insurance) that provide their own insurance option (FedEx, UPS, and Ontrac).

We recommend using Shippo's built-in insurance because it offers a more comprehensive coverage at a lower price.

<Info>
  **note**

  To learn more about how XCover works with Shippo, see our [XCover help article](https://support.goshippo.com/hc/en-us/articles/18146261565083-Introducing-New-Enhanced-Shipping-Insurance-with-XCover#introducing-new-enhanced-shipping-insurance-with-xcover-0-0).
</Info>

## Insurance for single package shipments using XCover

For shipments consisting of only one package, you can specify insurance directly from the Shipment object.

<Info>
  **note**

  It's important to review the XCover coverage details.

  * For details on shipments originating from the US, refer to [this guide on shipping protection](https://www.xcover.com/en-us/pds/shipping-protection-shippo-us?utm_source=xcms\&utm_medium=pds\&utm_campaign=parcel_insurance_v1).
  * For details on shipments originating from outside of the US (CA, UK, France, Spain, Italy, Netherlands, Germany), refer to [this guide on shipping protection](https://www.xcover.com/en-us/pds/shipping-protection-shippo-ca?utm_source=xcms\&utm_medium=pds\&utm_campaign=parcel_insurance_v1).

  XCover provides insurance for shipments and parcels up to an `amount` of \$10,000 USD. Depending on the source country, this limit can vary.
</Info>

Make sure to specify the `amount` and `currency`, as well as `content` within the `insurance` attribute inside ShipmentExtras attribute. The `provider` will default to Shippo's insurance provider.

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/shipments/\
      -H "Authorization: ShippoToken <API_Token>"\
      -d address_from="d799c2679e644279b59fe661ac8fa488"\
      -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
      -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
      -d extra='{"insurance": {"amount": "200", "currency": "USD", "content": "t-shirts" }}'\
      -d async=false
  ```

  ```Python {% title="Python" %} theme={null}
  import shippo
  from shippo.models import components

  shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

  address_from = components.AddressCreateRequest(
      name="Shawn Ippotle",
      street1="215 Clayton St.",
      city="San Francisco",
      state="CA",
      zip="94117",
      country="US",
      phone="+1 555 341 9393",
      email="shippotle@shippo.com"
  )

  address_to = components.AddressCreateRequest(
      name="Mr Hippo",
      street1="Broadway 1",
      city="New York",
      state="NY",
      zip="10007",
      country="US",
      phone="+1 555 341 9393",
      email="mrhippo@shippo.com"
  )

  parcel = components.ParcelCreateRequest(
      length="5",
      width="5",
      height="5",
      distance_unit=components.DistanceUnitEnum.IN,
      weight="2",
      mass_unit=components.WeightUnitEnum.LB
  )

  insurance = components.Insurance(
      amount="200",
      currency="USD",
      content="t-shirts"
  )

  shipment = shippo_sdk.shipments.create(
      components.ShipmentCreateRequest(
          address_from=address_from,
          address_to=address_to,
          parcels=[parcel],
          extra=components.ShipmentExtra(
              insurance=insurance
          )
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'shippotle@shippo.com'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'street1' => 'Broadway 1',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'mrhippo@shippo.com'
  );

  $parcel = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $insurance = array(
      'amount' => '200',
      'currency' => 'USD',
      'content' => 't-shirts'
  );

  $shipment = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "parcels" => array($parcel),
          "async" => false,
          "extra" => array("insurance" => $insurance)
      )
  );
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const addressFrom: AddressCreateRequest = {
      name: "Shawn Ippotle",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com"
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      street1: "Broadway 1",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
      phone: "+1 555 341 9393",
      email: "mrhippo@shippo.com"
  };

  const parcel: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const insurance: Insurance = {
      amount: "200",
      currency: "USD",
      content: "t-shirts"
  };

  const shipment = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
      async: true,
      extra: { insurance: insurance }
  });
  ```

  ```Java {% title="Java" %} theme={null}
  Shippo.setApiKey('<API_Token>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");
  addressToMap.put("phone", "+1 555 341 9393");
  addressToMap.put("email", "mrhippo@goshipppo.com");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");
  addressFromMap.put("email", "mshippo@goshipppo.com");
  addressFromMap.put("phone", "+1 619 231 1515");
  addressFromMap.put("metadata", "Customer ID 123456");

  // Parcel
  HashMap<String, Object> parcelMap = new HashMap<String, Object>();
  parcelMap.put("length", "5");
  parcelMap.put("width", "5");
  parcelMap.put("height", "5");
  parcelMap.put("distance_unit", "in");
  parcelMap.put("weight", "2");
  parcelMap.put("mass_unit", "lb");

  // Insurance
  HashMap<String, Object> insuranceMap = new HashMap<String, Object>();
  insuranceMap.put("amount", "200");
  insuranceMap.put("currency", "USD");
  insuranceMap.put("content", "t_shirts");

  // Extra
  HashMap<String, Object> extraMap = new HashMap<String, Object>();
  extraMap.put("insurance", insuranceMap);

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("extra", extraMap);
  shipmentMap.put("async", false);

  Shipment shipment = Shipment.create(shipmentMap);
  ```

  ```cs C# {% title="C#" %} theme={null}
  using Shippo;
  using Shippo.Models.Components;
  ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_Token>");
  AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Shawn Ippotle",
          Street1 = "215 Clayton St.",
          City = "San Francisco",
          State = "CA",
          Zip = "94117",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "shippotle@shippo.com",
      }
  );
  AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
      new AddressCreateRequest()
      {
          Name = "Mr Hippo",
          Street1 = "Broadway 1",
          City = "New York",
          State = "NY",
          Zip = "10007",
          Country = "US",
          Phone = "+1 555 341 9393",
          Email = "mrhippo@shippo.com",
      }
  );
  Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
      new ParcelCreateRequest()
      {
          Length = "5",
          Width = "5",
          Height = "5",
          DistanceUnit = DistanceUnitEnum.In,
          Weight = "2",
          MassUnit = WeightUnitEnum.Lb,
      }
  );
  Insurance insurance = new Insurance()
  {
      Amount = "200",
      Currency = "USD",
      Content = "t-shirts",
  };
  Shipment shipment = await sdk.Shipments.CreateAsync(
      new ShipmentCreateRequest()
      {
          AddressFrom = addressFrom,
          AddressTo = addressTo,
          Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
          Extra = new ShipmentExtra()
          {
              Insurance = insurance,
          },
          Async = false,
      }
  );
  ```
</CodeGroup>

Each valid Shipment object request will trigger a number of Rate objects that contain the shipment insurance information.
The field `included_insurance_price` indicates the insurance fee for the requested coverage. That fee is also included in the rate "amount" as well.

```json theme={null}
{
    "status": "SUCCESS",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@shippo.com",
    "address_from": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "address_to": {
        "object_id": "4c7185d353764d0985a6a7825aed8ffb",
        "validation_results": {},
        "is_complete": true,
        "name":"Mrs. Hippo",
        "street1":"965 Mission St.",
        "city":"San Francisco",
        "state":"CA",
        "zip":"94105",
        "country":"US",
        "phone":"+1 555 341 9393",
        "email":"support@shippo.com",
        "is_residential": false
    },
    "address_return": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "parcels": [{
        "object_id": "ec952343dd4843c39b42aca620471fd5",
        "object_created": "2013-12-01T06:24:21.121Z",
        "object_updated": "2013-12-01T06:24:21.121Z",
        "object_owner": "shippotle@shippo.com",
        "template": null,
        "length":"5",
        "width":"5",
        "height":"5",
        "distance_unit":"in",
        "weight":"2",
        "mass_unit":"lb",
        "value_amount": null,
        "value_currency": null,
        "metadata": "",
        "line_items": [],
        "test": true
    }],
    "shipment_date": "2013-12-03T12:00:00.000Z",
    "extra": {
        "insurance": {
            "amount": "200",
            "currency": "USD",
            "content": "t-shirts"
        },
        "reference_1": "",
        "reference_2": ""
    },
    "customs_declaration": "",
    "rates": [
        {
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@shippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "included_insurance_price": "1.05",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
                "name": "Priority Mail",
                "token": "usps_priority",
                "terms": "",
                "extended_token": "usps_priority",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false,
            "zone": "20"
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": [],
    "test": false
}
```

You can then create the shipping label by POSTing to the Transaction endpoint as usual:

<CodeGroup>
  ```shell {% title="cURL" %} theme={null}
  curl https://api.goshippo.com/transactions\
      -H "Authorization: ShippoToken <API_Token>"\
      -d rate="cf6fea899f1848b494d9568e8266e076"
      -d label_file_type="PDF"
      -d async=false
  ```

  ```Python {% title="Python" %} theme={null}
  shippo_sdk.transactions.create(
      components.TransactionCreateRequest(
          rate=shipment.rates[0].object_id,
          label_file_type=components.LabelFileTypeEnum.PDF,
          async_=False
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  require_once('lib/Shippo.php');
  Shippo::setApiKey("<API_Token>");

  $fromAddress = array(
      'name' => 'Shawn Ippotle',
      'street1' => '215 Clayton St.',
      'city' => 'San Francisco',
      'state' => 'CA',
      'zip' => '94117',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'shippotle@shippo.com'
  );

  $toAddress = array(
      'name' => 'Mr Hippo"',
      'street1' => 'Broadway 1',
      'city' => 'New York',
      'state' => 'NY',
      'zip' => '10007',
      'country' => 'US',
      'phone' => '+1 555 341 9393',
      'email' => 'mrhippo@shippo.com'
  );

  $parcel = array(
      'length'=> '5',
      'width'=> '5',
      'height'=> '5',
      'distance_unit'=> 'in',
      'weight'=> '2',
      'mass_unit'=> 'lb',
  );

  $insurance = array(
      'amount' => '200',
      'currency' => 'USD',
      'content' => 't-shirts'
  );

  $shipment = Shippo_Shipment::create(
      array(
          "address_from" => $fromAddress,
          "address_to" => $toAddress,
          "parcels" => array($parcel),
          "async" => false,
          "extra" => array("insurance" => $insurance)
      )
  );
  ```

  ```typescript {% title="TypeScript" %} theme={null}
  const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

  const addressFrom: AddressCreateRequest = {
      name: "Shawn Ippotle",
      street1: "215 Clayton St.",
      city: "San Francisco",
      state: "CA",
      zip: "94117",
      country: "US",
      phone: "+1 555 341 9393",
      email: "shippotle@shippo.com"
  };

  const addressTo: AddressCreateRequest = {
      name: "Mr Hippo",
      street1: "Broadway 1",
      city: "New York",
      state: "NY",
      zip: "10007",
      country: "US",
      phone: "+1 555 341 9393",
      email: "mrhippo@shippo.com"
  };

  const parcel: ParcelCreateRequest = {
      length: "5",
      width: "5",
      height: "5",
      distanceUnit: DistanceUnitEnum.In,
      weight: "2",
      massUnit: WeightUnitEnum.Lb
  };

  const insurance: Insurance = {
      amount: "200",
      currency: "USD",
      content: "t-shirts"
  };

  const shipment = await shippo.shipments.create({
      addressFrom: addressFrom,
      addressTo: addressTo,
      parcels: [parcel],
      async: true,
      extra: { insurance: insurance }
  });
  ```

  ```Java {% title="Java" %} theme={null}
  Shippo.setApiKey('<API_Token>');

  // To Address
  HashMap<String, Object> addressToMap = new HashMap<String, Object>();
  addressToMap.put("name", "Mr Hippo");
  addressToMap.put("company", "Shippo");
  addressToMap.put("street1", "215 Clayton St.");
  addressToMap.put("city", "San Francisco");
  addressToMap.put("state", "CA");
  addressToMap.put("zip", "94117");
  addressToMap.put("country", "US");
  addressToMap.put("phone", "+1 555 341 9393");
  addressToMap.put("email", "mrhippo@goshipppo.com");

  // From Address
  HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
  addressFromMap.put("name", "Ms Hippo");
  addressFromMap.put("company", "San Diego Zoo");
  addressFromMap.put("street1", "2920 Zoo Drive");
  addressFromMap.put("city", "San Diego");
  addressFromMap.put("state", "CA");
  addressFromMap.put("zip", "92101");
  addressFromMap.put("country", "US");
  addressFromMap.put("email", "mshippo@goshipppo.com");
  addressFromMap.put("phone", "+1 619 231 1515");
  addressFromMap.put("metadata", "Customer ID 123456");

  // Parcel
  HashMap<String, Object> parcelMap = new HashMap<String, Object>();
  parcelMap.put("length", "5");
  parcelMap.put("width", "5");
  parcelMap.put("height", "5");
  parcelMap.put("distance_unit", "in");
  parcelMap.put("weight", "2");
  parcelMap.put("mass_unit", "lb");

  // Insurance
  HashMap<String, Object> insuranceMap = new HashMap<String, Object>();
  insuranceMap.put("amount", "200");
  insuranceMap.put("currency", "USD");
  insuranceMap.put("content", "t_shirts");

  // Extra
  HashMap<String, Object> extraMap = new HashMap<String, Object>();
  extraMap.put("insurance", insuranceMap);

  // Shipment
  HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
  shipmentMap.put("address_to", addressToMap);
  shipmentMap.put("address_from", addressFromMap);
  shipmentMap.put("parcels", parcelMap);
  shipmentMap.put("extra", extraMap);
  shipmentMap.put("async", false);

  Shipment shipment = Shipment.create(shipmentMap);
  ```

  ```cs C# {% title="C#" %} theme={null}
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateTransactionCreateRequest(
          new TransactionCreateRequest()
          {
              Rate = shipment.Rates[0].ObjectId,
              LabelFileType = LabelFileTypeEnum.Pdf,
              Async = false,
          }
      )
  );
  ```
</CodeGroup>

## Insurance for single package shipments using carrier insurance

You can purchase insurance directly from a carrier by specifying your `provider` within the `insurance` attribute inside ShipmentExtras attribute. This is available only for FedEx, UPS, and Ontrac.

```shell cURL theme={null}
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_Token>"\
    -d address_from="d799c2679e644279b59fe661ac8fa488"\
    -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
    -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
    -d extra='{"insurance": {"amount": "200", "currency": "USD", "content": "t-shirts", "provider":"FEDEX" }}'\
    -d async=false
```

## Insurance for multi-piece shipments

For multi-piece shipments you can choose to purchase specific insurance amounts for each package. This can be done through the [extras](/api-reference/parcels/list-all-parcels) attribute when creating your Parcel object within the Shipment request.

The following example shows a request to add insurance to each parcel in a multi-piece shipment using carrier provided insurance.
To add insurance using XCover, omit `provider` from your request.

```shell cURL theme={null}
curl https://api.goshippo.com/shipment/\
-H "Authorization: ShippoToken <API_Token>"\
-H "Content-Type: application/json"\
-d '{
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "address_to": "42236bcf36214f62bcc6d7f12f02a849",
    "parcels": [
        {
            "length": "5",
            "width": "5",
            "height": "5",
            "distance_unit": "cm",
            "weight": "2",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box1",
            "extra": {
                "insurance": {
                    "amount": 25.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "5",
            "width": "10",
            "height": "15",
            "distance_unit": "cm",
            "weight": "6",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box2",
            "extra": {
                "insurance": {
                    "amount": 50.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "2",
            "width": "8",
            "height": "9",
            "distance_unit": "cm",
            "weight": "5",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box3",
            "extra": {
                "insurance": {
                    "amount": 45.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        }
    ],
    "async": false
}
```

## Handling shipment-level and parcel-level insurance

If both shipment-level and parcel-level insurance are specified, the parcel-level insurance will take precedence. Parcels without parcel-level insurance will have the shipment-level insurance amount applied to that parcel.

If only shipment-level insurance is specified, then the shipment insurance amount will be applied to each parcel and not divided amongst parcels.

## Canceling or refunding insurance

Please see our page on [Refunds](/billing-and-invoices/refunding-labels) for more info on refunding insured shipments.


# Shipping label sizes
Source: https://docs.goshippo.com/shipments/shipping-label-sizes

Choose from multiple shipping label formats and sizes including PDF, PNG, and ZPL when purchasing labels through Shippo.

Use this guide to learn how to use the Shippo API to create different label sizes for your application.

## Setting your label format

Specify your preferred label format by setting the `label_file_type` parameter to one of the [label tokens](#shipping-label-format-sizes) when calling the [transaction endpoint](/api-reference/transactions/create-a-shipping-label) to purchase your label.

Each carrier supports different label size options. Refer to our [carrier capabilities](/carriers/carrier-capabilities) for carrier specific details.

If you don't set the `label_file_type`, the Shippo API will use the default format set in the [Shippo dashboard](https://apps.goshippo.com/settings/labels).

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "rate": "a5c9d1bec93149f5bedc3a9374b50970",
  "async": false,
  "label_file_type": "PDF"
}'
```

## Shipping label format sizes

| Label type         | Dimensions (imperial) | Dimensions (metric) | Token         |
| ------------------ | --------------------- | ------------------- | ------------- |
| 2.3 x 7.5 inch PDF | 2.3 x 7.5 inch        | 59 x 191 mm         | `PDF_2.3x7.5` |
| 2.3 x 7.5 inch PNG | 2.3 x 7.5 inch        | 59 x 191 mm         | `PNG_2.3x7.5` |
| 4 x 8 inch PDF     | 4 x 8 inch            | 100 x 200 mm        | `PDF_4x8`     |
| 4×6 inch PDF       | 4 x 6 inch            | 102 x 153 mm        | `PDF_4x6`     |
| 8.5×11 inch PDF    | 8.5 x 11 inch         | 210 x 279 mm        | `PDF`         |
| A4 PDF             | 8.3 x 11.7 inch       | 210 x 297 mm        | `PDF_A4`      |
| A5 PDF             | 5.8 x 8.3 inch        | 148 x 210 mm        | `PDF_A5`      |
| A6 PDF             | 4.1 x 5.8 inch        | 105 x 148 mm        | `PDF_A6`      |
| ZPL II             |                       |                     | `ZPLII`       |
| PNG                |                       |                     | `PNG`         |


# Authorization
Source: https://docs.goshippo.com/shipping-elements/auth

Set up secure authorization for Shippo Shipping Elements using JWT tokens for white label and gray label integrations.

To create secure access to Shippo Shipping Elements follow this guide.

## Background

There are two ways for you to enable your user to create their own shipping labels using Shipping Elements.
Shipping Elements supports both gray label and white label integrations.

* Using a white label integration means that you create and manage you users accounts using [Shippo Platforms](/platform-accounts/platform-accounts). Shippo bills your account and you're responsible for billing users. This provides a seamless experience for your user. You have access to all account details including access keys.

* Using a gray label integration means that you guide your user to create their own Shippo account that you have access to using [OAuth](/o-auth-integrations/o-auth). Shippo will bill your users directly.

For each use case, keys are long lived and suitable only for server-side communication where the key can be kept private.
For secure access to Shippo accounts using Shippo Shipping Elements, this guide details how to obtain a short lived token ([JSON Web Token (JWT)](https://jwt.io/)). These JWT expire after 12 hours.

Follow the steps here to generate a JWT.

## White label integration

If you have not already, review our guide on [Shippo Platform accounts](/platform-accounts/platform-accounts). You must have a Platforms account to create and use Managed Shippo Accounts.

### 1. Retrieve your user's Shippo Account ID

When you [create a Shippo Managed account](/platform-accounts/platform-using-accounts#create-a-managed-shippo-account-for-your-customer) for your user, the response includes an `object_id` that you will use to reference that account. This is the Shippo Account ID that you can use to make API calls representing that account. When you create the account, you should save this `object_ id` along with your users account credentials.

If you need to retrieve a Shippo Account ID of an account, you can request a list of all your Managed Shippo Accounts.

```shell cURL theme={null}
  curl --location --request GET 'https://api.goshippo.com/shippo-accounts/' \
  --header 'Authorization: ShippoToken <API_TOKEN>' \
  --header 'Content-Type: application/json'
```

The response includes the `object_id` for each account.

### 2. Generate your own JWT using direct authorization API

To generate a JWT for a Managed account, call the `embedded/authz/` endpoint and set the `object_id` from the previous step to the `SHIPPO-ACCOUNT-ID` in the header of the call.

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'SHIPPO-ACCOUNT-ID: e0b382dc7d754c0ca6358c09d5d2bdf7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

The following is the expected response.

```json theme={null}
// response
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}
```

Where `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

## Get your OAuth key

If you have not already, follow the steps in our [guide to request your OAuth key and get access to a Bearer Token](/o-auth-integrations/o-auth).

## Generate your own JWT

There are 2 ways you can generate your own JWT.

#### Direct Authorization API

The first way to generate your JWT is to call the `/embedded/authz/` endpoint.
Send the following request. Remember to replace `<OAUTH_BEARER_TOKEN>` with your Bearer Token.

```shell theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: Bearer <OAUTH_BEARER_TOKEN> \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

The following is the expected response.

```json theme={null}
// response
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}
```

Where `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.

#### User Server Side Remote Procedure Call to generate JWT

The second way to generate your JWT is to use RPC.

```JAVA theme={null}
service user {
  rpc DirectAuthorization(DirectAuthorizationRequest) : DirectAuthorizationResponse
}

message DirectAuthorizationRequest {
 context
 requestor: // integration user id
 requested_subject: // alice's id
 token_type: 'jwt'
}
```

Expected Response

```JAVA theme={null}
message DirectAuthorizationResponse {
  token: 
  // encoded jwt
  expires: 
  //unix timestamp representing when the token expires
}
```

## Validate your JWT

JWT works the same as an API token. To test your generated JWT, call the [list all carrier parcel templates](/api-reference/carrier-parcel-templates/list-all-carrier-parcel-templates) endpoint. Remember to replace `<JWT_TOKEN>` with the token you have generated.

```shell theme={null}
curl --location --request GET https://api.goshippo.com/parcel-templates  \
    --header 'Authorization: JWT <JWT_TOKEN>' \
    --header 'Content-Type: application/json'
```

If your JWT is functioning correctly, you should see a response like this.

```json theme={null}
[
  {
    "name": "FedEx® Small Box (S1)",
    "token": "FedEx_Box_Small_1",
    "carrier": "FedEx",
    "is_variable_dimensions": false,
    "length": "12.375",
    "width": "10.875",
    "height": "1.5",
    "distance_unit": "in"
  }
]
```

## Strategy for generating JWT

Your generated JWT expires after 12 hours. When integrating Shippo Shipping Elements, consider how you will automatically generate this for your user.
The flow below shows how to generate a JWT and how to refresh an expired JWT for your user. Use this with the [Shipping Elements events](/shipping-elements/events) to integrate the token generation into your site.

<img alt="Shippo Shipping Elements User Interface" />

<img alt="Shippo Shipping Elements User Interface" />


# Bulk labels
Source: https://docs.goshippo.com/shipping-elements/bulk

Use Shippo Shipping Elements to let your merchants purchase up to 50 shipping labels at once with bulk label creation.

## What is bulk label purchasing?

In Shippo, bulk label purchasing is a tool for creating labels for multiple orders in a single batch. Purchasing labels in a batch helps your merchants save time and effort.
Merchants can create up to 50 labels at a time.

The bulk flow enables the following.

* Merchants see a list of their orders.
* The UI prompts your merchant to complete required details that are missing.
* Merchants can edit their shipment details in the UI for each order.
* Merchants can print labels and packing slips with a single click.

The following shows an example of bulk label purchase flow in Elements.

<img alt="Image showing bulk label purchase" />

## Enable bulk in Elements

Bulk is available to all Elements users. To start a bulk label purchase flow, call `labelPurchase` and pass `orderDetails` as [an array](/shipping-elements/install#parameters-1). Each element of the array contains the details for an individual order.

This example shows two orders added to Elements that starts the bulk label purchase flow.

```html Bulk example in Elements theme={null}
<!doctype html>
<html class="no-js" lang="">
<head>
        <meta charset="utf-8">
        <title>Web Application</title>
</head>
<body>
    <button id="purchaseLabelButton">Purchase Label</button>
    <div id="shippoWidget"></div>
    <script src="https://js.goshippo.com/embeddable-client.js"></script>
    <script type="application/javascript">
      if (shippo) {
        shippo.init({
          token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
          org: 'john-doe-industries',
          locale: 'fr-CA',
          theme: {
            width: '100%',
          },
        });
      }
      document.getElementById('purchaseLabelButton').addEventListener('click', (event) => {
      	event.preventDefault();
        shippo.labelPurchase('#shippoWidget', {
          address_to: {
            name: 'William Faulkner',
            company: '',
            street1: '916 Old Taylor Rd',
            city: 'Oxford',
            state: 'MS',
            zip: '38655',
            country: 'US',
            phone: '662-234-3284',
            email: 'william@rowanoak.com',
          },
          line_items: [
            {
              title: 'hitchhikers guide to the galaxy',
              sku: 'TS-42',
              quantity: 1,
              currency: 'USD',
              unit_amount: '12',
              unit_weight: '0.40',
              weight_unit: 'lb',
              country_of_origin: 'US',
            }
          ],
          order_number: '12345'
        },
        {
          address_to: {
            name: 'John Daley',
            company: '',
            street1: '107 Wolf Pen Road',
            city: 'San Francisco',
            state: 'CA',
            zip: '394107',
            country: 'US',
            phone: '882-985-5421',
            email: 'john@ymail.com',
          },
          line_items: [
            {
              title: 'A brief history of time',
              sku: 'TS-662',
              quantity: 1,
              currency: 'USD',
              unit_amount: '12',
              unit_weight: '0.40',
              weight_unit: 'lb',
              country_of_origin: 'US',
            }
          ],
          order_number: '87667'
        }
        
        );
      }, false);
    </script>
</body>
</html>

```


# Customization
Source: https://docs.goshippo.com/shipping-elements/customisation

Customize the look of Shippo Shipping Elements in your site using theme options for colors, buttons, cards, and more.

You can change how Shippo Shipping Elements looks in your site using the `theme` parameter when calling the [init method](/shipping-elements/install).

## Theme

Here are all supported theme values:

```typescript theme={null}
export interface Theme {
  elementId?: string;
  title?: string;
  style?: string;
  height?: string;
  width?: string;
  primaryColor?: string;
  container?: {
    backgroundColor?: string;
  };
  header?: {
    backgroundColor?: string;
    borderColor?: string;
    color?: string;
    hasBoxShadow?: boolean;
    textAlign?: 'left' | 'right' | 'center';
  };
  footer?: {
    backgroundColor?: string;
    borderColor?: string;
    hasBoxShadow?: boolean;
  };
  button?: {
    primary: {
      backgroundColor?: string;
      activeBackgroundColor?: string;
      hoverColor?: string;
      color?: string;
      borderRadius?: string;
      borderColor?: string;
      activeBorderColor?: string;
      textTransform?: 'lowercase' | 'uppercase' | 'capitalize';
      disabledBackgroundColor?: string;
      disabledBorderColor?: string;
      disabledTextColor?: string;
    };
    secondary?: {
      backgroundColor?: string;
      activeBackgroundColor?: string;
      color?: string;
      borderRadius?: string;
      borderColor?: string;
      activeBorderColor?: string;
      textTransform?: 'lowercase' | 'uppercase' | 'capitalize';
      disabledBackgroundColor?: string;
      disabledBorderColor?: string;
      disabledTextColor?: string;
    };
  };
  cards?: {
    subHeaderColor?: string;
    backgroundColor?: string;
    borderRadius?: string;
    borderColor?: string;
    borderStyle?: string;
    hoverBackgroundColor?: string;
    activeBackgroundColor?: string;
};
  inputs?: {
    borderColor?: string;
    borderActive?: string;
    hoverColor?: string;
  };
  menu?: {
    titleBackgroundColor?: string;
    hoverColor?: string;
    hoverBackgroundColor?: string;
  };
}
```


# Elements Data Flow
Source: https://docs.goshippo.com/shipping-elements/data-flow

Understand how data flows between Shippo Shipping Elements and your web application, including best practices.

The following is an overview of the data flow between Elements and your web application and includes some best practices for data ownership.

## Ownership of data

While the Elements application can operate in isolation and used by users to purchase labels within a user session, some key points of integration can provide greater benefit to your application and the general user experience. Some of these cases can include the following:

### Saving the tracking number and shipment status

After purchasing a shipping label, you may want to save and display the fulfillment status and/or tracking number of the shipment in your interface. Both of these properties are available in the `LABEL_PURCHASED` event (see docs here: [Shipping Elements Events](/shipping-elements/events)). This event includes some crucial information such as:

* Estimated time of arrival
* Tracking number
* Total cost
* Shipping Label link
* Packing Slip URL
* Status

While users can view all of this information in Elements, you may choose to take the data from the event callback function, save on your server and display it in your application. This could save the user an extra step of opening elements to view this information or provide the information for internal usage such as reporting or analytics.

<Info>
  **Note**

  If you are relying on elements to provide access to tracking information or links to download labels in a session **after** the label was created, save and pass the order `object_id` into the `OrderDetails` object of the `labelPurchase()` function to load the order. See below for more information.
</Info>

### Persisting label creation edits across Shipping Elements sessions

On the initial render of Shipping Elements, you can choose to load an existing order or create a new order and this logic is dictated by the `object_id` passed in through the [OrderDetails object](/shipping-elements/install#orderdetails) to the `labelPurchase` function. This `object_id` is a unique representation of an order in our system. These are the same orders that a user will see if logging into the Shippo web application and are necessary to save and persist a user's changes/selections related to the shipping label.

When an order is created in elements, an `ORDER_CREATED` event is emitted (see docs here: [Shipping Elements Events](/shipping-elements/events)). It is recommended to save the `order_id` and associate it with the order in your web application. It can then be passed as the `object_id` to labelPurchase for future sessions to maintain the edits and state of the order. This is particularly important for the following cases:

* User has made some edits to the label, but has not yet purchased
* The user has purchased a label and is looking to view tracking information or download the label/packing slip

If an `object_id` is not passed, Shipping Elements will assume you want to create a new shipping label. This may also represent duplicate orders in the Shippo web application for a singular order within your web application.

Below is a diagram of the data flow of order information through events:

<img alt="Shipping Elements Data Flow" />


# Elements release notes
Source: https://docs.goshippo.com/shipping-elements/elements-change-log

View the release notes and recent updates for Shippo Shipping Elements, including bug fixes and new features.

<Info>
  **Note**

  To learn about updates to Shippo API view the [Shippo API release notes](/api-concepts/api-change-log).
</Info>

### Mar 15 2024 v3.1.0

* DHL Express have updated their shipping requirements. To support our users to continue to use DHL Express, we've update Shipping Elements to include a new interface and flow for users to accept DHL's new terms and conditions.
* We've updated the Shipping Elements interface for users enabling the carrier Canada Post.

### Jan 23 2023 v3.0.5

* We've fixed a bug where previously pressing the back button in your address book caused an unexpected behavior.

### Dec 01 2023 v3.0.3

* We've made changes to the Elements user interface to improve rates and orders pages.

### Sep 20 2023 v2.3.0

* Soon, USPS will require sender addresses include a valid email address and phone number for each shipment. To keep our users compliant, we've updated Shipping Elements to check for a valid email address and phone number before purchasing a USPS label. Shipping Elements directs users to update their address if these details are missing.
* We've fixed a bug where previously, for some international addresses, our address autocomplete was not functioning as expected and causing address validation to fail.

### Sep 14 2023 v2.2.0

* We've expanded our cross-border shipping in Shipping Elements to include international shipping from all locations.
* We have updated the UI to improve the error message that Shipping Elements displays for authorization errors.

### Aug 31 2023 v2.1.2

* Shipping Elements now includes [XCover](https://www.xcover.com/en-us/help/partners/shippo) as Shippo's new shipping insurance provider.
* We've expanded our cross-border shipping in Shipping Elements to include international shipping from Canada.

### Aug 16 2023 v2.1.0

* We've fixed a bug where in certain situations Shipping Elements did not retrieve the from address and return address correctly.

### Aug 14 2023 v2.0.0

* Elements now supports shipping hazardous materials.
* We've updated some of the styling used on our package details in the Shipping Elements interface.
* Cross-border shipping has now been enabled for Shipping Elements supporting international shipping from the US.
* We've added checks to ensure weights are included for customs items.
* We've added commercial invoices to Shipping Elements.

### Aug 11 2023 v1.6.0

* We found a bug where in specific situations duplicate orders could be created. That bug is now fixed.

### Aug 01 2023 v1.5.4

* We've fixed a bug in our UI where in specific situations the **Next** button was displayed incorrectly.

### Jul 11 2023 v1.5.2

* We've updated the styling for address book.

### Jun 30 2023 v1.5.1

* Elements now supports USPS Hazmat classification.

### Jun 27 2023 v1.5.0

* Elements now supports address validation of the addresses saved in the address book.
* We've fixed a bug with address book where an older address was being used incorrectly.

### Jun 08 2023 v1.4.0

* Elements now includes an address book. Users can edit, add, delete addresses.
* We've updated weight unit defaults based on a user's location.

### May 25 2023 v1.3.2

* We've fixed a bug where the wrong logo was displayed for carrier packages.

### May 22 2023 v1.3.1

* We've added a "Choose Package" page where users can select carrier packages and recently used packages.
* Elements users can now delete package templates that they have created.
* Elements users can use their defaults for weight and dimension units when adding package details to an order.

### May 03 2023 v1.3.0

* We've added search to the "Choose Package" page making it easier for users to find the package they want to use.
* We've added the option to add a new package template to the "Choose Package" page.

### Apr 26 2023 v1.2.0

* We've fixed a bug where the automatic insurance option was causing an error.

### Apr 17 2023 v1.1.0

* We've fixed a bug where invalid addresses were not displayed as invalid.
* Elements now selects a default rate. The user can use this rate or select other rates available to them.
* Elements users can now purchase labels using an invalid address. Before purchasing, users will be prompted to confirm their decision.
* Elements users can now ship domestically in Spain using carrier Correos.
* Elements users can now ship domestically in France using carrier Colissimo.

### Apr 05 2023 v1.0.0

* Elements now includes an insurance settings view
* Elements now includes options to change labels and packaging slips.

### Mar 31 2023 v0.0.47

* We've improved the feedback from address validation to direct users to fix issues with the addresses they have provided.
* We've added a company info settings page where you can display information about your own company that will be used on your packing slips, tracking pages, and emails for your customers.

### Mar 23 2023 v0.0.46

* Elements now includes a warning message indicating a selected rate has changed after adding insurance and/or signature confirmation.
* A bug has been fixed where negative numbers could be added to the insurance field.
* We've added address validation to Elements.
* We've added a feature that all ELements users with US to US shipments will see the option to add insurance.

### Mar 16 2023 v0.0.45

* We fixed a bug where users saw incorrect insurance offerings.

### Mar 13 2023 v0.0.43

* We've fixed a bug where a user could purchase a label before new rates were retrieved.

### Mar 10 2023 v0.0.42

* We fixed a bug where an error was created when adding options for insurance or required signature

### Mar 10 2023 v0.0.41

* We've made some changes to the look and feel of Elements
* We've fixed a bug where removing signature confirmation from purchase summary card inline also removed remove insurance

### Mar 03 2023 v0.0.40

* We've added an option for user to add insurance at the time of purchase.
* We've added a purchase summary to Element. Now, before purchasing a label, users will see a summary.
* Elements now supports the addition of signature confirmation. When this is selected, received packages will require a signature from the recipient.
* Elements can now be used in a white label configuration where all billing is managed by the site owner and all Shippo logos can be hidden.

### Feb 13 2023 v0.0.38

* We've added new messaging to inform users who are shipping outside of a supported region to inform them that the region is not supported.
* We fixed a bug for users in Germany where DHL was not displayed as a shipping option.

### Feb 06 2023 v0.0.37

* We've added support for USPS First-Class Package/Mail Parcel

### Jan 19 2023 v0.0.35

* Elements now supports generating return labels at time of purchase for carriers that support that feature.

### Dec 22 2022 v0.0.34

* We fixed a bug to only display relevant carriers for cross-border shipments.
* We've improved our messaging to show carrier warning messages for failed rates.
* To support shipping to a German address, we've added checks to ensure the 2-character abbreviation has been added.
* We've added better messaging to support failed transactions so users can correct the issue or ask for help.

### Dec 12 2022 v0.0.30

* We've improved the address fields in Elements to support German and UK addresses
* We've updated Elements to support intra EU from Germany using Deutsche Post and DPD. Wealso added support for UK domestic shipment with DPD & Evri.

### Nov 29 2022 v0.0.28

* We've improved the process flow for Elements.  Users can now revise labels with bad fields, make changes, and purchase revised labels.

### Nov 15 2022 v0.0.26

* We've improved interactions with rates in Elements. You can now select and deselect rates in the interface.

### Nov 08 2022 v0.0.25

* We've made up updates to improve the look and feel of Elements user interface


# Error and Debugging
Source: https://docs.goshippo.com/shipping-elements/errors

Handle errors and debug issues in Shippo Shipping Elements using event listeners and the onAny logging method.

## Errors

All errors coming from the Shipping Elements can be accessing using an event listener on the `ERROR` event documented in [Events](/shipping-elements/events). For example:

```javascript theme={null}
shippo.on('ERROR', (error) => {
    switch (error.code) {
      case 'UNAUTHORIZED':
          // The authentication token is malformed, expired or otherwise invalid.
          break;
      case 'LABEL_PURCHASE_ERROR':
        // An error occurred during label purchase
        break;
      case 'COUNTRY_NOT_SUPPORTED':
        // To or from address country is not supported
        break;
      case 'LOCALE_NOT_SUPPORTED':
        // Locale passed in the init function is not supported
        break;
      case 'UNKNOWN':
        // An unknown error happened
        break;
    }
});
```

## Debugging

You can use the various [event handlers](/shipping-elements/events) to help debug the application. There is also a special `onAny()` method that will handle any events from Shippo Shipping Elements:

```javascript theme={null}
shippo.onAny((params) => {
  // Log any events thrown from Shippo Shipping Elements
  console.log(params);
});
```


# Events
Source: https://docs.goshippo.com/shipping-elements/events

Use Shippo Shipping Elements events to respond to user actions like label purchases, order creation, and errors.

The Shippo Shipping Elements supports events that you can use to integrate with your website.

## Events using `shippo.on()`

The Shipping Elements framework emits lifecycle and action events as the user is interacting with the widget. Event listeners can be added using the `on()` method as such:

```javascript theme={null}
shippo.on('LABEL_PURCHASED_SUCCESS', (event) => {
    // do something when the user purchases a label!
});
```

## Event List

| Event                     | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| APP\_READY                | The widget is rendered and ready to receive configuration or events. |
| CLOSE\_BUTTON\_CLICKED    | The user clicked the close button to close the widget.               |
| ORDER\_CREATED            | A Shippo order object was created for the data passed into Elements. |
| LABEL\_PURCHASED\_SUCCESS | A label was successfully purchased.                                  |
| ERROR                     | Any error has occurred.                                              |
| ORDERS\_CREATED           | Shippo orders object was created for the data passed into Elements.  |
| ORDERS\_CREATED\_ERROR    | Something went wrong in created orders within our system.            |

<Info>
  **note**

  Using the `shippo.off()` method removes the listener for that callback event.
</Info>

## Event Parameters

Each event has unique parameters to the callback function, here are some examples:

### LABEL\_PURCHASED\_SUCCESS

The `LABEL_PURCHASED_SUCCESS` event returns an array of transaction objects as the parameter to the callback function passed to the `on()` method:

```typescript theme={null}
interface Transaction {
    shipment_id?: string;
    order_id?: string;
    commercial_invoice_url?: string;
    eta?: string;
    entry_point?: string;
    label_url?: string;
    messages?: any[];
    metadata?: string;
    object_created?: string;
    object_updated?: string;
    object_id?: string;
    object_owner?: string;
    object_state?: string;
    object_status?: string;
    packing_slip_url?: string;
    rate?: WebRate;
    refund_request_date?: string;
    tracking_number?: string;
    tracking_url_provider?: string;
    was_test?: boolean;
}
```

### ORDER\_CREATED

The `ORDER_CREATED` event returns a shipment object with the order\_id as the parameter to the callback function passed to the `on()` method:

```typescript theme={null}
interface OrderCreatedParams {
  order_id: string;
  shipment_id?: string;
  address_from?: {
    ip?: string;
    is_residential?: boolean;
    latitude?: string;
    longitude?: string;
    metadata?: string;
    object_created?: string;
    object_id?: string;
    object_purpose?: 'PURCHASE' | 'QUOTE';
    object_source?: string;
    object_state?: string;
    object_updated?: string;
  };
  address_return?: {
    ip?: string;
    is_residential?: boolean;
    latitude?: string;
    longitude?: string;
    metadata?: string;
    object_created?: string;
    object_id?: string;
    object_purpose?: 'PURCHASE' | 'QUOTE';
    object_source?: string;
    object_state?: string;
    object_updated?: string;
  };
  address_to?: {
    ip?: string;
    is_residential?: boolean;
    latitude?: string;
    longitude?: string;
    metadata?: string;
    object_created?: string;
    object_id?: string;
    object_purpose?: 'PURCHASE' | 'QUOTE';
    object_source?: string;
    object_state?: string;
    object_updated?: string;
  };
  alternate_address_to?: string;
  carrier_accounts?: object[];
  customs_declaration?: {
    /** Automated Export System Internal Transaction Number (exports from USA) */
    aes_itn?: string;
    /** Name of the person who created the customs declaration and is responsible for the validity of all information provided */
    authorized_person: string;
    /** B13A Export Declaration, mandatory for Canadian exports valued at CAD$2000 or more */
    b13a_filing_option?: 'FILED_ELECTRONICALLY' | 'NOT_REQUIRED' | 'SUMMARY_REPORTING';
    /** Proof of Report Number, Summary ID Number, or Exemption Number, depending on B13A filing option */
    b13a_number?: string;
    certificate?: string;
    /** Exemption and Exclusion Legend / Proof of Filing Citation (exports from USA) */
    eel_pfc?: 'NOEEI_30_37_a' | 'NOEEI_30_37_h' | 'NOEEI_30_37_f' | 'NOEEI_30_36' | 'AES_ITN';
    exporter_reference?: string;
    importer_reference?: string;
    incoterm?: 'DDP' | 'DDU' | 'FCA';
    invoice_number?: string;
    /** Expresses that the certify_signer has provided all information of this customs declaration truthfully */
    is_certified: boolean;
    is_vat_collected?: boolean;
    items: {
      /** export control classification number (ECCN/EAR99) for US exports */
      control_classification?: string;
      description: string;
      is_test?: boolean;
      /** @format uuid */
      line_item_object_id?: string;
      mass_unit: 'g'|'kg'|'oz'|'lb';
      metadata?: string;
      net_value?: string;
      net_weight?: string;
      /** @format uuid */
      object_id?: string;
      /**
       * ISO 3166-2 alpha-2 country code
       * @example "US"
       */
      origin_country?: string;
      object_state?: 'VALID' | 'INVALID';
      quantity: number;
      sku_code?: string;
      /** The item's tariff number, e.g. Harmonized System (HS) Codes */
      tariff_number?: string;
      unit_value: string;
      unit_weight: string;
      /**
       * ISO 4217 3-letter currency code
       * @example "USD"
       */
      value_currency: string;
    }[];
    license?: string;
    metadata?: string;
    non_delivery_handling?: 'ABANDON' | 'RETURN';
    notes?: string;
    /** Explanation of the type of goods of the shipment */
    purpose_explanation?: string;
    /** Reason for export */
    purpose_of_shipment?:
      | 'DOCUMENTS'
      | 'GIFT'
      | 'HUMANITARIAN_DONATION'
      | 'MERCHANDISE'
      | 'OTHER'
      | 'RETURN_MERCHANDISE'
      | 'SAMPLE';
    tax_id?: string;
    tax_id_type?: string;
  } | null;
  extras?: {
    alcohol?: {
      contains_alcohol?: boolean | null;
      recipient_type?: 'CONSUMER' | 'LICENSEE' | null;
    };
    dry_ice?: {
      contains_dry_ice?: boolean | null;
      /** @format float */
      weight?: number | null;
      weight_unit_id?: string | null;
    };
    insurance?: {
      amount?: string | null;
      content?: string | null;
      currency?: string | null;
      use_imported_amount?: boolean | null;
    };
    dangerous_goods?: {
      contains?: boolean | null;
      contains_lithium_batteries?: boolean | null;
      contains_biological_material?: boolean | null;
    };
    is_bypass_address_validation?: boolean | null;
    is_bypass_customs?: boolean | null;
    is_return_requested?: boolean | null;
    packing_slip_text?: string | null;
    signature_confirmation?: string | null;
  };
  is_return?: boolean;
  line_items?: {
    /** references to the ids of line_items in the WebOrder */
    object_id?: string;
    quantity?: number;
  }[];
  object_created?: string;
  object_owner?: string;
  object_updated?: string;
  parcels?: {
    distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
    height?: string;
    length?: string;
    mass_unit?: 'g'|'kg'|'oz'|'lb';
    use_item_weight?: boolean;
    weight?: string;
    width?: string;
    carrier_parcel_template?: {
      api_token?: string;
      distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
      height?: string;
      is_variable_dimensions?: boolean;
      length?: string;
      name?: string;
      carrier?: string;
      token?: string;
      width?: string;
    } | null;
    user_parcel_template?: {
      distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
      height?: string;
      is_default?: boolean;
      length?: string;
      name?: string;
      object_id?: string | null;
      template?: {
        api_token?: string;
        distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
        height?: string;
        is_variable_dimensions?: boolean;
        length?: string;
        name?: string;
        carrier?: string;
        token?: string;
        width?: string;
      } | null;
      weight?: string;
      weight_unit?: 'g'|'kg'|'oz'|'lb';
      width?: string;
    };
  }[];
  rates?: {
    amount?: string;
    amount_local?: string;
    arrives_by?: string;
    attributes?: string[];
    carrier_account?: string;
    currency?: string;
    currency_local?: string;
    duration_terms?: string;
    /** @format int32 */
    estimated_days?: number;
    included_insurance_price?: string;
    messages?: string[];
    object_created?: string;
    object_id?: string;
    object_owner?: string;
    provider?: string;
    provider_image_200?: string;
    provider_image_75?: string;
    servicelevel?: {
      extended_token?: string;
      name?: string;
      parent_servicelevel?: string;
      terms?: string;
      token?: string;
    };
    shipment?: string;
    test?: boolean;
    zone?: string;
  }[];
  shipment_date?: string;
  status?:
    | 'PENDING'
    | 'VALIDATING_ORDER'
    | 'VALID_ORDER'
    | 'INVALID_ORDER'
    | 'PROCESSING_SHIPMENT'
    | 'COMPLETE_SHIPMENT'
    | 'EXCLUDED_ORDER'
    | 'SHIPMENT_REQUEST_FAILED'
    | 'PROCESSING_TRANSACTION'
    | 'COMPLETE_TRANSACTION'
    | 'TRANSACTION_REQUEST_FAILED'
    | 'SHIPMENT_REQUEST_NOT_AVAILABLE'
    | 'RATE_NOT_AVAILABLE';
  transaction?: string;
}
```

The `ORDERS_CREATED` event sends an array of order objects (same as above) as the parameter to the callback function passed to the `on()` method.

### Errors

The `ERROR` event returns an error object as the parameter to the call function passed to the `on()` method:

```typescript theme={null}
interface Transaction {
    code: 'UNAUTHORIZED'|'LABEL_PURCHASE_ERROR'|'COUNTRY_NOT_SUPPORTED'|'LOCALE_NOT_SUPPORTED'|'UNKNOWN';
    detail: string;
}
```


# Introduction
Source: https://docs.goshippo.com/shipping-elements/index

Add shipping label purchasing directly to your website using Shippo Shipping Elements, with no custom UI required.

Use this guide to integrate Shippo Shipping Elements into your website.

<Info>
  **Note**

  To learn about updates to Shippo Elements view the [Shippo Elements changelog](/shipping-elements/elements-change-log).
</Info>

## What is Shippo Shipping Elements?

Shippo Shipping Elements is a feature that you can use to add shipping directly into your website without developing the user interface or the code behind it.

This guide shows you how to enable Shippo Shipping Elements in your website. When your user presses a button you have created, a popup window appears that supports your user in purchasing a shipping label.

<img alt="Shippo Shipping Elements user interface" />

## Who is this for?

We have developed functionality for Shippo partners who want to offer shipping functionality to their users.
If you run a website with users who need to ship items to their customers (like eBay), you can use Shippo Shipping Elements to integrate shipping directly into your site. This gives your users access to a shipping solution without leaving your site.

## How do I use it?

This site guides through the details of how to integrate Shippo Shipping Elements into your website. At it's simplest, all you need to do is setup authentication and copy our provided code into your site to get the Shipping Elements working.

Your users can fulfill orders with the Shipping Elements from within your website.

Before using Shippo Shipping Elements:

* Your user must create or login to their Shippo account
* You must integrate with Shippo's authentication method to authorize your user

On your website:

1. Your user can trigger label purchase workflow within the widget
2. You can pass details of their order into the widget
3. Shippo displays their order within the widget
4. Your user can fulfill their order, adding details to generate, and compare rates among carriers
5. Your user can purchase and download their label
6. You are notified of the purchase and fulfillment information

## Why would I use this?

Using Shippo Shipping Elements helps to integrate with Shippo experience immediately. Follow the steps in this guide to quickly and easily start using Shippo in your application.
This means you spend less time worrying about how to integrate, and more time focusing on your product.

## Features

* Create and buy shipping label
* Add package dimensions and weight
* Get shipping rates
* Tracking
* Shipping label refund
* Manage addresses
* Format labels and packing slips
* View billing and invoices
* Print shipping label and packing slip


# Install the Shippo Shipping Elements SDK
Source: https://docs.goshippo.com/shipping-elements/install

Install the Shippo Shipping Elements SDK and configure the init and labelPurchase methods to render the widget.

The Shippo Shipping Elements SDK is a client-side javascript SDK that provides mechanisms for rendering and controlling the Shipping Elements shipping workflow.

## Installation

To install the SDK, include the javascript file from our Content Delivery Network (CDN): `https://js.goshippo.com/embeddable-client.js` (32 kb file size) on your web application just before the closing `</body>` tag.

For example:

```html theme={null}
<!doctype html>
<html class="no-js" lang="">
<head>
    <meta charset="utf-8">
    <title>Web Application</title>
</head>
<body>
    App content.
    <script src="https://js.goshippo.com/embeddable-client.js"></script>
</body>
</html>
```

This script initializes a `shippo` window variable that contains variables and methods for using the SDK.

## Overview

The Shippo Shipping Elements SDK has two primary methods for setting up and rendering the Shipping Elements label purchase flow: `init()` and `labelPurchase()`. The `init()` method authenticates and configures all Shippo widgets and is typically called once per page. The `labelPurchase()` function renders the widget and passes any required data to prepopulate shipment information such as address, order items, etc. The `labelPurchase()` method may be called multiple times per page as the user is creating shipping labels for multiple orders.

## `init()` - Initialize the widget framework

Once you have generated a valid authentication token ([JWT](/shipping-elements/auth)), you will call the `init` function from the window-scoped `shippo` variable:

```javascript theme={null}
shippo.init()
```

### Parameters

The `init` function takes an object of the following:

* **token**: string (required) - a JWT-style authentication token derived [from the /authz endpoint](/shipping-elements/auth)
* **org**: string (required) - an identifier for your organization
* **locale**: string (optional, defaults to `en-US`) - The locale string in "IETF language tag" format used to translate the widget.
  Supported values:
  * en
  * en-GB
  * ru
  * de
  * fr
  * tr
  * it
  * es
  * pl
  * uk
  * nl
  * en-au
* **theme**: Theme (optional) - Custom theme for the Shippo Shipping Elements. See [Theme](/shipping-elements/customisation#theme) documentation for supported values.

### Full example

Here is a full example of the `init()` method:

```javascript theme={null}
shippo.init({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
  org: 'john-doe-industries',
  locale: 'fr-CA',
  theme: {
    width: '100%',
  },
});
```

## `labelPurchase()` - Start label purchase flow

When you want the widget rendered, typically on a "Purchase Shipping Label" button click or equivalent, you will call the `labelPurchase()` method with the selector of the element you want to render the widget inside of and any shipment information you would like to prepopulate. You will call the `labelPurchase` function from the window-scoped `shippo` variable:

```javascript theme={null}
shippo.labelPurchase()
```

### Parameters

* **element**: string (required) - a document.querySelector-compatible selector for the element that the widget would be rendered inside of
* **orderDetails**: OrderDetails|OrderDetails\[] (required) - a JSON object (or array of JSON objects) with details about the order to be fulfilled

### OrderDetails

```typescript theme={null}
export interface Address {
      name: string;
      company?: string;
      street_no?: string;
      street1: string;
      street2?: string;
      street3?: string;
      city: string;
      state: string;
      zip: string;
      country: string;
      phone?: string;
      email?: string;
}
export interface Item {
      id?: number;
      title: string;
      sku?: string;
      quantity: number;
      currency: string;
      unit_amount: string;
      unit_weight: string;
      weight_unit: string;
      country_of_origin?: string;
}
export interface OrderDetails {
      address_from?: Address;
      address_to: Address;
      line_items: Item[];
      address_return?: Address;
      object_id?: string;
      order_number?: string;
      order_status?: string;
      placed_at?: string;
      notes?: string;
      // end of order information
      shipment_date?: Date;
      extras?: {
        insurance?: {
          amount: string;
          currency: string;
        };
        signature_confirmation?: string;
      };
}
```

### Full example

Here is a full example of the `labelPurchase()` method for a single order:

```javascript theme={null}
  shippo.labelPurchase('#shippoWidget', {
        address_to: {
              name: 'William Faulkner',
              company: '',
              street1: '916 Old Taylor Rd',
              city: 'Oxford',
              state: 'MS',
              zip: '38655',
              country: 'US',
              phone: '662-234-3284',
              email: 'william@rowanoak.com',
        },
        line_items: [
          {
                title: 'Book',
                sku: 'TS-123',
                quantity: 1,
                currency: 'USD',
                unit_amount: '12',
                unit_weight: '0.40',
                weight_unit: 'lb',
                country_of_origin: 'US',
            }
        ],
        order_number: '12345'
  });
```

And an example for multiple orders:

```javascript theme={null}
    shippo.labelPurchase('#shippoWidget', [
      {
        address_to: {
          name: 'William Faulkner',
          company: '',
          street1: '916 Old Taylor Rd',
          city: 'Oxford',
          state: 'MS',
          zip: '38655',
          country: 'US',
          phone: '662-234-3284',
          email: 'william@rowanoak.com',
        },
        line_items: [
          {
            title: 'Book',
            sku: 'TS-123',
            quantity: 1,
            currency: 'USD',
            unit_amount: '12',
            unit_weight: '0.40',
            weight_unit: 'lb',
            country_of_origin: 'US',
          }
        ],
        order_number: '12345'
      },
      {
        address_to: {
          name: 'John Steinbeck',
          company: '',
          street1: '132 Central Ave, Salinas, CA 93901',
          city: 'Salinas',
          state: 'CA',
          zip: '93901',
          country: 'US',
          phone: '831-424-2735',
          email: 'admin@steinbeckhouse.net',
        },
        line_items: [
          {
            title: 'Book',
            sku: 'TS-123',
            quantity: 1,
            currency: 'USD',
            unit_amount: '12',
            unit_weight: '0.40',
            weight_unit: 'lb',
            country_of_origin: 'US',
          }
        ],
        order_number: '23456'
      }
    ]);
```

## Full Example (install, init and labelPurchase)

```html theme={null}
<!doctype html>
<html class="no-js" lang="">
<head>
        <meta charset="utf-8">
        <title>Web Application</title>
</head>
<body>
    <button id="purchaseLabelButton">Purchase Label</button>
    <div id="shippoWidget"></div>
    <script src="https://js.goshippo.com/embeddable-client.js"></script>
    <script type="application/javascript">
      if (shippo) {
        shippo.init({
          token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
          org: 'john-doe-industries',
          locale: 'fr-CA',
          theme: {
            width: '100%',
          },
        });
      }
      document.getElementById('purchaseLabelButton').addEventListener('click', (event) => {
      	event.preventDefault();
        shippo.labelPurchase('#shippoWidget', {
          address_to: {
            name: 'William Faulkner',
            company: '',
            street1: '916 Old Taylor Rd',
            city: 'Oxford',
            state: 'MS',
            zip: '38655',
            country: 'US',
            phone: '662-234-3284',
            email: 'william@rowanoak.com',
          },
          line_items: [
            {
              title: 'Book',
              sku: 'TS-123',
              quantity: 1,
              currency: 'USD',
              unit_amount: '12',
              unit_weight: '0.40',
              weight_unit: 'lb',
              country_of_origin: 'US',
            }
          ],
          order_number: '12345'
        });
      }, false);
    </script>
</body>
</html>
```


# Shippo Shipping Elements quickstart
Source: https://docs.goshippo.com/shipping-elements/quickstart

Try Shippo Shipping Elements with our live demo or run the React sample app locally to see how it works.

Use this quickstart guide to help understand what Shipping Elements is, see how it looks and works, and quickly setup your own application. This is one example implementation created in React using the [CreateReactApp](https://github.com/facebook/create-react-app). For more information on integrating Shipping Elements into your own website, follow the rest of the [Shipping Elements guide](/shipping-elements/index).

## Try Shipping Elements

You can use a working example of Shipping Elements in our [demo site](https://goshippo.github.io/shipping-elements-react-demo/).

1. Using the Shippo web app, get your [Shippo token](/guides/authentication). For testing, we recommend you use your Shippo test token
2. Use your Shippo token to create a JWT using the `authz` endpoint. Replace `<API_TOKEN>` with your token

```shell theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'
```

For more information on authorization in Shipping Elements, see our [authorization guide](/shipping-elements/auth)
3\. Paste your generated JWT into our [demo site](https://goshippo.github.io/shipping-elements-react-demo/)
4\. Select **Purchase Label** to view and interact with the application

## Run Shipping Elements locally

You can also run Shipping Elements on your local system. Before you begin, you must have [Node installed](https://nodejs.org/en).

Complete the following steps to run Shipping Elements locally.

1. Clone or download the following repository to local system
   [https://github.com/goshippo/shipping-elements-react-demo](https://github.com/goshippo/shipping-elements-react-demo)
2. Using your console, navigate to the project directory
3. Run the following command to install the project dependencies

```shell theme={null}
npm install
```

4. Run the following command to run the application in development mode

```shell theme={null}
npm start
```

5. Open [http://localhost:3000](http://localhost:3000) in your browser to view and interact with the application


# Ship to international customers
Source: https://docs.goshippo.com/stories/intl-rating-guide

Follow a step-by-step guide to ship internationally with the Shippo API, including customs declarations and label purchase.

**Meet Sarah**

<img alt="picture of user Sarah" />

Sarah owns a guitar distribution website, **[www.wesellguitars.net](http://www.wesellguitars.net)**. They have been steadily growing for the past eight years. Until now, Sarah has focused on the US market but lately has been getting requests from Europe to start selling there too. She wants to expand her business and sees this as a great opportunity.

To begin, she wants to start small and learn. She’s going to start shipping guitar pedals to the UK.

To start, Sarah [creates an address object](/api-reference/addresses/create-a-new-address) for her “for address”. For international shipping, it is essential the address object for both sender and recipient contains a phone number.
The response includes the `object_id` of her premises address that can be reused throughout her application. If she ever changes her premises, it’s easy for her to update this information in a single location rather than updating in a number of different places in her application.

```shell Create address request theme={null}
curl --location 'https://api.goshippo.com/addresses/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Sarah",
    "company":"We Sell Guitars",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "sarah@wesellguitars.net",
    "is_residential": "False",
    "metadata":"We Sell Guitars HQ"
}'

```

```json Create address response theme={null}
{
    "object_created": "2023-07-26T12:14:05.145Z",
    "object_updated": "2023-07-26T12:14:05.155Z",
    "object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
    "is_complete": true,
    "validation_results": {},
    "object_owner": "sarah@wesellguitars.net",
    "name": "Sarah",
    "company": "We Sell Guitars",
    "street_no": "",
    "street1": "215 Clayton St.",
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "longitude": null,
    "latitude": null,
    "phone": "0015553419393",
    "email": "sarah@wesellguitars.net",
    "is_residential": false,
    "metadata": "We Sell Guitars HQ",
    "test": true
}
```

For international shipments, you must include a [customs declaration](/international-shipping/international-shipping#create-a-customs-declaration-and-customs-items). Sarah uses this example to create hers.

```shell Create customs declaration request theme={null}
curl --location 'https://api.goshippo.com/customs/declarations/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{          
  "contents_type": "MERCHANDISE",
  "non_delivery_option": "RETURN",
  "certify": true,
  "certify_signer": "Tom Marks",
  "incoterm": "DDP",
  "items": [{
          "description": "Guitar Pedal",
          "quantity": 1,
          "net_weight": "5",
          "mass_unit": "lb",
          "value_amount": "200",
          "value_currency": "USD",
          "tariff_number": "",
          "origin_country": "US"
  }]
}'

```

```json Create customs declaration response theme={null}
{
    "object_created": "2023-07-26T12:20:27.408Z",
    "object_updated": "2023-07-26T12:20:27.408Z",
    "object_id": "3793642fe422479aab94e446ba9d648f",
    "object_owner": "sarah@wesellguitars.net",
    "object_state": "VALID",
    "address_importer": null,
    "certify_signer": "Tom Marks",
    "certify": true,
    "items": [
        "29608b4814d44f4cbb42b0f28223a660"
    ],
    "non_delivery_option": "RETURN",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "",
    "exporter_reference": "",
    "importer_reference": "",
    "invoice": "",
    "commercial_invoice": false,
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "",
    "aes_itn": "",
    "disclaimer": "",
    "incoterm": "DDP",
    "metadata": "",
    "test": true,
    "duties_payor": null,
    "b13a_filing_option": "",
    "b13a_number": "",
    "invoiced_charges": null,
    "exporter_identification": null,
    "is_vat_collected": false
}
```

Creating an international shipment is the same as creating a [domestic shipment](/guides/generate-shipping-label#create-a-shipment-object) with the addition of a customs declaration.

Sarah wants to ship with confidence and wants her international customers to be confident about their purchase so she’s added insurance to her shipments too.

```shell Create shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": "9d4bb72a14fe42c19e63a563c3a7abd7",
  "address_to": {
          "name": "Tom Marks",
          "street1": "159 Broadhurst Gardens",
          "city": "London",
          "zip": "NW6 3AU",
          "country": "GB",
          "phone": "4159876543",
          "email": "tommarks@gmmail.com"
  },
    "parcels":{
            "weight": "5",
            "length": "10",
            "width": "5",
            "height": "4",
            "distance_unit": "in",
            "mass_unit": "lb"
            },
    "customs_declaration": "3793642fe422479aab94e446ba9d648f",
  "extra.insurance": {"amount": "200", "currency": "USD", "content": "guitar pedal" },
  "async": false
}'
```

```json Create shipment request response theme={null}
{
    "carrier_accounts": [],
    "object_created": "2023-07-26T12:36:05.526Z",
    "object_updated": "2023-07-26T12:36:07.279Z",
    "object_id": "d0feffbc471f4d75b8be276739a79839",
    "object_owner": "sarah@wesellguitars.net",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
        "is_complete": true,
        "name": "Sarah",
        "company": "We Sell Guitars",
        "street_no": "",
        "street1": "215 Clayton St.",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "0015553419393",
        "email": "sarah@wesellguitars.net",
        "is_residential": false,
        "test": true
    },
    "address_to": {
        "object_id": "39e1c6ddd250477788202ce8c7a51dc0",
        "is_complete": true,
        "name": "Tom Marks",
        "company": "",
        "street_no": "",
        "street1": "159 Broadhurst Gardens",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "NW6 3AU",
        "country": "GB",
        "phone": "4159876543",
        "email": "tommarks@gmmail.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2023-07-26T12:36:05.500Z",
            "object_updated": "2023-07-26T12:36:05.532Z",
            "object_id": "f2602a1e13d34250b9e05267cd0efa87",
            "object_owner": "sarah@wesellguitars.net",
            "template": null,
            "extra": {},
            "length": "10.0000",
            "width": "5.0000",
            "height": "4.0000",
            "distance_unit": "in",
            "weight": "5.0000",
            "mass_unit": "lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2023-07-26T12:36:05.645Z",
    "address_return": {
        "object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
        "is_complete": true,
        "name": "Sarah",
        "company": "We Sell Guitars",
        "street_no": "",
        "street1": "215 Clayton St.",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "0015553419393",
        "email": "sarah@wesellguitars.net",
        "is_residential": false,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": {
        "object_created": "2023-07-26T12:20:27.408Z",
        "object_updated": "2023-07-26T12:36:05.515Z",
        "object_id": "3793642fe422479aab94e446ba9d648f",
        "object_owner": "sarah@wesellguitars.net",
        "object_state": "VALID",
        "address_importer": null,
        "certify_signer": "Tom Marks",
        "certify": true,
        "items": [
            "29608b4814d44f4cbb42b0f28223a660"
        ],
        "non_delivery_option": "RETURN",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "notes": "",
        "eel_pfc": "",
        "aes_itn": "",
        "disclaimer": "",
        "incoterm": "DDP",
        "metadata": "",
        "test": true,
        "duties_payor": null,
        "b13a_filing_option": "",
        "b13a_number": "",
        "invoiced_charges": null,
        "exporter_identification": null,
        "is_vat_collected": false
    },
    "extra": {},
    "rates": [
        {
            "object_created": "2023-07-26T12:36:05.729Z",
            "object_id": "65d6e49881864e63994519909a607d2d",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [],
            "amount": "76.97",
            "currency": "USD",
            "amount_local": "59.66",
            "currency_local": "GBP",
            "provider": "DHL Express",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/DHL.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/DHL.png",
            "servicelevel": {
                "name": "Worldwide",
                "token": "dhl_express_worldwide",
                "terms": "",
                "extended_token": "dhl_express_worldwide",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": "23:59:00",
            "duration_terms": "",
            "messages": [],
            "carrier_account": "50fb8af2e7a849b89db4fc02fa207f01",
            "test": true,
            "zone": "C",
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:06.281Z",
            "object_id": "da6ff1989fa74b0aa086118a3873c375",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [
                "FASTEST"
            ],
            "amount": "97.46",
            "currency": "USD",
            "amount_local": "75.55",
            "currency_local": "GBP",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Worldwide Express Plus®",
                "token": "ups_express_plus_worldwide_eu",
                "terms": "",
                "extended_token": "ups_express_plus_worldwide_eu",
                "parent_servicelevel": {
                    "extended_token": "ups_express_plus",
                    "name": "Worldwide Express Plus®",
                    "terms": "",
                    "token": "ups_express_plus"
                }
            },
            "estimated_days": 2,
            "arrives_by": "09:00:00",
            "duration_terms": "",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:06.281Z",
            "object_id": "792f8dddee0149e48c7a8d06fbaf6fa2",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [],
            "amount": "57.86",
            "currency": "USD",
            "amount_local": "44.85",
            "currency_local": "GBP",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Express®",
                "token": "ups_express",
                "terms": "",
                "extended_token": "ups_express_eu",
                "parent_servicelevel": {
                    "extended_token": "ups_express_worldwide",
                    "name": "Worldwide Express®",
                    "terms": "",
                    "token": "ups_express"
                }
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Next day delivery by 10:30 a.m. or 12:00 noon.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:06.281Z",
            "object_id": "5d3df0b7638e413b8d8061bbf6bd0a50",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [
                "BESTVALUE"
            ],
            "amount": "53.90",
            "currency": "USD",
            "amount_local": "41.78",
            "currency_local": "GBP",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Saver®",
                "token": "ups_saver",
                "terms": "",
                "extended_token": "ups_saver_eu",
                "parent_servicelevel": {
                    "extended_token": "ups_saver",
                    "name": "Saver®",
                    "terms": "",
                    "token": "ups_saver"
                }
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery usually in 1-3 business days.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:06.281Z",
            "object_id": "833c28c75ffb4dfcaed15324578dad69",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "48.18",
            "currency": "USD",
            "amount_local": "37.35",
            "currency_local": "GBP",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Expedited®",
                "token": "ups_expedited",
                "terms": "",
                "extended_token": "ups_expedited_eu",
                "parent_servicelevel": {
                    "extended_token": "ups_expedited_worldwide",
                    "name": "Worldwide Expedited®",
                    "terms": "",
                    "token": "ups_expedited"
                }
            },
            "estimated_days": 4,
            "arrives_by": null,
            "duration_terms": "Delivery time usually 2-5 business days.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:07.261Z",
            "object_id": "99913f5c1fbe4091b84253ac38872843",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [],
            "amount": "80.83",
            "currency": "USD",
            "amount_local": "62.65",
            "currency_local": "GBP",
            "provider": "USPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/USPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/USPS.png",
            "servicelevel": {
                "name": "Priority Mail International",
                "token": "usps_priority_mail_international",
                "terms": "",
                "extended_token": "usps_priority_mail_international",
                "parent_servicelevel": null
            },
            "estimated_days": 8,
            "arrives_by": null,
            "duration_terms": "Delivery in 6 to 10 business days.",
            "messages": [],
            "carrier_account": "b19e750708384303ac19ca693fe037ce",
            "test": true,
            "zone": "20",
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-26T12:36:07.261Z",
            "object_id": "81748d1fa1ec4f59b6dd33f735d40e26",
            "object_owner": "sarah@wesellguitars.net",
            "shipment": "d0feffbc471f4d75b8be276739a79839",
            "attributes": [],
            "amount": "92.90",
            "currency": "USD",
            "amount_local": "72.00",
            "currency_local": "GBP",
            "provider": "USPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/USPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/USPS.png",
            "servicelevel": {
                "name": "Priority Mail Express International",
                "token": "usps_priority_mail_express_international",
                "terms": "",
                "extended_token": "usps_priority_mail_express_international",
                "parent_servicelevel": null
            },
            "estimated_days": 4,
            "arrives_by": null,
            "duration_terms": "Delivery in 3 to 5 business days.",
            "messages": [],
            "carrier_account": "b19e750708384303ac19ca693fe037ce",
            "test": true,
            "zone": "20",
            "included_insurance_price": null
        }
    ],
    "messages": [
        {
            "source": "ShippoCommon",
            "code": "shipment_date_not_eligibl",
            "text": "Shipment to or from countries other than the US are not allowed"
        },
        {
            "source": "UPS",
            "code": "113005",
            "text": "RatedShipmentAlert: The selected service may not guarantee early AM arrival to the requested location."
        },
        {
            "source": "UPS",
            "code": "112239",
            "text": "RatedShipmentAlert: International movement is not in scope"
        },
        {
            "source": "UPS",
            "code": "110971",
            "text": "RatedShipmentAlert: Your invoice may vary from the displayed reference rates"
        }
    ],
    "metadata": "",
    "test": true,
    "order": null
}
```

Sarah then uses her preferred Rate to [purchase the label](/guides/generate-shipping-label#create-a-transaction-object).

```shell Purchase label request theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "rate": "78ac2f9710a543a3836cf985be8fa304",
  "async": false,
  "label_file_type": "PDF"
}'
```


# Split a shipment into multiple packages
Source: https://docs.goshippo.com/stories/multi-piece-guide

Learn how to ship multiple packages to the same customer in a single multi-piece shipment using the Shippo API.

**Meet Fred**

<img alt="Fred picture" />

Fred runs an online pet furniture business, **[www.fred-bed.com](http://www.fred-bed.com)**. He doesn’t own any physical store, his customers purchase pet furniture online. He sells dog beds that his customers customize with their favorite cushion.
He has learned that it’s easier for him to ship the cushion and bed in separate packages.

Fred needs to know how to multi-ship his items, to make it easier for his business and to save money. He also needs to share the tracking information with his customers so they can track the progress of their packages.

Fred creates [parcels](/api-reference/parcels/create-a-new-parcel) for each part of his order that he can use over and over.

```shell theme={null}
curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 50,
  "width": 30,
  "height": 30,
  "distance_unit": "cm",
  "weight": 10,
  "mass_unit": "kg",
  "template": "",
  "metadata": "Bed-Base-1-of-2"
}'

```

```shell theme={null}
curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 50,
  "width": 30,
  "height": 10,
  "distance_unit": "cm",
  "weight": 5,
  "mass_unit": "kg",
  "template": "",
  "metadata": "Tartan-pattern-2-of-2"
}'
```

The response includes the object ID for the parcels that were created.

```json theme={null}
"object_id": "ed07d387707d477090066befcccd3d2b"
"object_id": "efad281d588a456c85be772133de50db"
```

These parcels can then be used to create a multi-piece [shipment](/guides/generate-shipping-label#create-a-shipment-object). The response is the shipment object that includes rate options for the shipment. The rates show the cost (`amount`) for both parcels together.
In the background, when Fred creates the shipment with multiple parcels, the Shippo API does the work to create the multi-piece shipment, hiding the complexity from Fred.

```shell Create shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
                "name": "Fred",
                "street1": "215 Clayton St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94117",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@fred-bed.com"
            },
  "address_to": {
                "name": "Mrs. Hippo",
                "street1": "965 Mission St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94105",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@shippo.com"
            },
  "parcels": [ "ed07d387707d477090066befcccd3d2b", "efad281d588a456c85be772133de50db"],
  "extra": {},
  "async": false
}'

```

```json Create shipment response theme={null}
"rates": [
        {
            "object_created": "2023-07-25T15:43:52.528Z",
            "object_id": "4f0d1707d8d442bd8c9faf6e7a5c4829",
            "object_owner": "support@fred-bed.com",
            "shipment": "65d7dc06708342238772a0dafab9b7b4",
            "attributes": [
                "FASTEST"
            ],
            "amount": "121.18",
            "currency": "USD",
            "amount_local": "121.18",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air® Early",
                "token": "ups_next_day_air_early_am",
                "terms": "",
                "extended_token": "ups_next_day_air_early_am",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "08:30:00",
            "duration_terms": "Next business day delivery by 8:30 a.m., 9:00 a.m., or 9:30 a.m. ",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        }
]
```

Fred can purchase the labels by passing the rate to the [transaction endpoint](/guides/generate-shipping-label#create-a-transaction-object).
The response is a list of transaction objects, one transaction for each parcel.
Fred can use the `label_url` to print labels for each parcel.

The `tracking_number` from the response is the principal (`mstr`) tracking number of the entire Shipment. This tracking number associates all tracking numbers in the shipment.
As an example, [this label](https://shippo-static.s3.amazonaws.com/img/illustrations/mps2.png) has the `mstr` tracking number on it that includes information about the status of the entire multi-piece shipment.

```shell Purchase label request theme={null}
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "4f0d1707d8d442bd8c9faf6e7a5c4829",
  "label_file_type": "PDF",
  "async": false
}'
```

```json Purchase label response theme={null}
{
   "results":[
      {
         "object_state":"VALID",
         "status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"support@fred-bed.com",
         "was_test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":{
            "object_created":"2014-07-17T00:43:50.402Z",
            "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
            "status":"UNKNOWN",
            "status_details":"",
            "status_date":null
         },
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "eta":"2014-07-21T12:00:00.000Z",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "commercial_invoice_url": "",
         "messages":[

         ],
         "metadata":""
      },
      {...},
      {...}
   ]
}
```


# Get a shipping label
Source: https://docs.goshippo.com/stories/single-rating-guide

Follow a step-by-step guide to get shipping rates and purchase a label using the Shippo API for your first shipment.

**Meet Rachael**

<img alt="Rachael picture" />

Rachael is a small e-commerce business owner, **[www.alltheyarnz.com](http://www.alltheyarnz.com)**, who specializes in selling yarn to hobbyists. Until now, she has exclusively used the Shippo web app to manage her shipping. As her business has been growing, she's looking for ways to become more efficient.  She now ships approximately 40,000 packages a year.
She needs to integrate Shippo into her workflow to automatically find the best available service levels for her.
Looking at her past sales, 10% of the orders have the same weight and size, that means she can use the same size box. She has decided that this is a good place for her to start working with the Shippo API.

First, to simplify the process, Rachael creates a parcel object. Because she only uses one parcel size, it makes sense for her to [create a parcel object](/api-reference/parcels/create-a-new-parcel) that can be referenced over and over again.

```shell Create parcel request theme={null}
curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 5,
  "width": 5,
  "height": 5,
  "distance_unit": "cm",
  "weight": 2,
  "mass_unit": "lb",
  "template": "",
  "metadata": "Wool Box1"
}'
```

```json Create parcel response  theme={null}
{
    "object_state": "VALID",
    "object_created": "2023-07-25T14:41:41.953Z",
    "object_updated": "2023-07-25T14:41:41.953Z",
    "object_id": "d1a39a2feea94decabbf78eb69a91d50",
    "object_owner": "rachael@alltheyarnz.com",
    "template": null,
    "length": "5.0000",
    "width": "5.0000",
    "height": "5.0000",
    "distance_unit": "cm",
    "weight": "2.0000",
    "mass_unit": "lb",
    "value_amount": null,
    "value_currency": null,
    "metadata": "Wool Box1",
    "extra": {},
    "line_items": [],
    "test": true
}
```

Rachael uses UPS because they’re close to her home. To get shipping rates from her preferred carrier (UPS), she must first find the [object ID for that carrier](/api-reference/carrier-accounts/list-all-carrier-accounts).

```shell Get carrier account request theme={null}
curl --location 'https://api.goshippo.com/carrier_accounts/?carrier=ups' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

```json Get carrier account response theme={null}
{
  "carrier": "ups",
  "object_id": "f1f8b350f37c4147a592ac6877743ae4",
  "object_owner": "rachael@alltheyarnz.com",
  "account_id": "shippo_ups_account",
  "parameters": {},
  "test": true,
  "active": true,
  "is_shippo_account": true,
  "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"
  }
}
```

Using the `object_id` from her preferred carrier (UPS) in the `carrier_accounts` field, Rachael gets [rates for her parcel](/guides/generate-shipping-label#create-a-shipment-object). The response includes rates available to Rachael from only her preferred carrier.

```shell Create shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
          "name": "Rachael",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "rachael@alltheyarnz.com"
  },
  "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
  },
  "parcels":["d1a39a2feea94decabbf78eb69a91d50"],
  "carrier_accounts":["f1f8b350f37c4147a592ac6877743ae4"],
  "extra": {},
  "async": false
}'
```

```json Create shipment response theme={null}
"carrier_accounts": [
        "f1f8b350f37c4147a592ac6877743ae4"
    ],
    "object_created": "2023-07-25T15:03:57.668Z",
    "object_updated": "2023-07-25T15:03:57.669Z",
    "object_id": "0f26906a9aa54274a56a48e57a1c3338",
    "object_owner": "rachael@alltheyarnsz.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "d9795c6cf0de492d9de07a01d243e476",
        "is_complete": true,
        "name": "Rachael",
        "company": "",
        "street_no": "",
        "street1": "1092 Indian Summer Ct",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "rachael@alltheyarnz.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "db2fb0ee3fb048ac9d00f4b30972410f",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission St #572",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2023-07-25T14:41:41.953Z",
            "object_updated": "2023-07-25T15:03:57.685Z",
            "object_id": "d1a39a2feea94decabbf78eb69a91d50",
            "object_owner": "rachael@alltheyarnz.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "5.0000",
            "height": "5.0000",
            "distance_unit": "cm",
            "weight": "2.0000",
            "mass_unit": "lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "Wool Box1",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2023-07-25T15:03:57.634Z",
    "address_return": {
        "object_id": "d9795c6cf0de492d9de07a01d243e476",
        "is_complete": true,
        "name": "Rachael",
        "company": "",
        "street_no": "",
        "street1": "1092 Indian Summer Ct",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "rachael@alltheyarnz.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": null,
    "extra": {},
    "rates": [
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "90fa81e7dab14a19bd42ca2773482b89",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [
                "FASTEST"
            ],
            "amount": "48.11",
            "currency": "USD",
            "amount_local": "48.11",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air® Early",
                "token": "ups_next_day_air_early_am",
                "terms": "",
                "extended_token": "ups_next_day_air_early_am",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "08:30:00",
            "duration_terms": "Next business day delivery by 8:30 a.m., 9:00 a.m., or 9:30 a.m. ",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "80362bdfc6364ea8ae542478a12cf206",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "18.41",
            "currency": "USD",
            "amount_local": "18.41",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air®",
                "token": "ups_next_day_air",
                "terms": "",
                "extended_token": "ups_next_day_air",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "10:30:00",
            "duration_terms": "Next business day delivery by 10:30 a.m., 12:00 noon, or end of day, depending on destination.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "54c1d066fa00401e9ede4111e0519fb2",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "13.70",
            "currency": "USD",
            "amount_local": "13.70",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air Saver®",
                "token": "ups_next_day_air_saver",
                "terms": "",
                "extended_token": "ups_next_day_air_saver",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "15:00:00",
            "duration_terms": "Next business day delivery by 3:00 or 4:30 p.m. for commercial destinations and by end of day for residentail destinations.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "1d03331062d14b1eb327d178eb68956a",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [
                "BESTVALUE",
                "CHEAPEST"
            ],
            "amount": "6.18",
            "currency": "USD",
            "amount_local": "6.18",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Ground",
                "token": "ups_ground",
                "terms": "",
                "extended_token": "ups_ground",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": null,
            "duration_terms": "Delivery times vary. Delivered usually in 1-5 business days.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "2e30da53020f4d349db086fc73be3bc8",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "10.43",
            "currency": "USD",
            "amount_local": "10.43",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "2nd Day Air® A.M.",
                "token": "ups_second_day_air_am",
                "terms": "",
                "extended_token": "ups_second_day_air_am",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": "10:30:00",
            "duration_terms": "Delivery on the second business day by 10:30 a.m. or 12:00 noon to most commercial destinations.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "bdf9cd1ad6714465a134d53cb0307561",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "9.35",
            "currency": "USD",
            "amount_local": "9.35",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "2nd Day Air®",
                "token": "ups_second_day_air",
                "terms": "",
                "extended_token": "ups_second_day_air",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery by the end of the second business day.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.497Z",
            "object_id": "d903683a04014015a803c7e8ce2a9f64",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "8.92",
            "currency": "USD",
            "amount_local": "8.92",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "3 Day Select®",
                "token": "ups_3_day_select",
                "terms": "",
                "extended_token": "ups_3_day_select",
                "parent_servicelevel": null
            },
            "estimated_days": 3,
            "arrives_by": null,
            "duration_terms": "Delivery by the end of the third business day.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        }
    ],
    "messages": [
        {
            "source": "UPS",
            "code": "110971",
            "text": "RatedShipmentAlert: Your invoice may vary from the displayed reference rates"
        }
    ],
    "metadata": "",
    "test": true,
    "order": null
}
```

Using one of the returned rates, Rachael can then [purchase the label](/guides/generate-shipping-label#create-a-transaction-object).

```shell Purchase label request theme={null}
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "80362bdfc6364ea8ae542478a12cf206",
  "async": false
}'
```


# Accessing webhook subscriptions
Source: https://docs.goshippo.com/tracking/creating-webhooks

Register, retrieve, update, and delete webhook subscriptions programmatically using the Shippo Webhooks API.

## Registering a webhook for your account

To register a webhook for your account, make a POST request to the webhooks endpoint `https://api.goshippo.com/webhooks`.

```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/webhooks' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "<CLIENT_OWNED_URL>",
    "event": "<YOUR_EVENT>",
    "is_test": "true" //this value is defaulted to false and is optional
}'
```

The event field can take one of the following five values:

* `transaction_created`
* `transaction_updated`
* `track_updated`
* `batch_created`
* `batch_purchased`

Additionally, you can set the `event` to `all`. This acts as a catch-all for all supported events.

A successful call to the registration endpoint will return a JSON object.

```json theme={null}
{
    "active": true,
    "event": "<YOUR_EVENT>",
    "object_created": "2021-06-28T15:44:11.647Z",
    "object_id": "<WEBHOOK_OBJECT_ID_GUID>",
    "object_updated": "2021-06-28T15:44:11.647Z",
    "object_owner": "<Account Owner Email>",
    "url": "<CLIENT_REGISTERED_URL>",
    "is_test": true
}
```

## Retrieving a single webhook

To retrieve a webhook, make a GET request to the webhooks endpoint with the object ID of your webhook `https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>`.

```shell cURL theme={null}
curl --location --request GET 'https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' 
```

A successful call returns a JSON object similar to this.

```json theme={null}
{
    "active": true,
    "event": "<YOUR_EVENT>",
    "object_created": "2021-06-28T15:44:11.647Z",
    "object_id": "<WEBHOOK_OBJECT_ID_GUID>",
    "object_updated": "2021-06-28T15:44:11.647Z",
    "object_owner": "<Account Owner Email>",
    "url": "<CLIENT_REGISTERED_URL>",
    "is_test": true
}
```

To get a paginated list of all webhooks associated with your account, make a GET request to `https://api.goshippo.com/webhooks` without an object ID.

## Retrieving all active webhooks

To retrieve a list of all webhooks associated with your account, make a GET request to the webhooks endpoint `https://api.goshippo.com/webhooks/`.

```shell cURL theme={null}
curl --location --request GET 'https://api.goshippo.com/webhooks/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' 
```

A successful call returns a JSON object similar to this.

```json theme={null}
{
    {
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "active": true,
      "event": "track_updated",
      "object_created": "2023-01-26T17:37:56.848Z",
      "object_id": "9c9783fa0e1148c98eba040141801119",
      "object_updated": "2023-01-26T17:37:56.848Z",
      "object_owner": "<Account Owner Email>",
      "url": "<CLIENT_REGISTERED_URL>",
      "is_test": false
    },
    {
      "active": true,
      "event": "track_updated",
      "object_created": "2023-01-26T17:36:34.715Z",
      "object_id": "a346d9e481b14dcfb6df48c19bfeacca",
      "object_updated": "2023-01-26T17:36:34.715Z",
      "object_owner": "<Account Owner Email>",
      "url": "<CLIENT_REGISTERED_URL>",
      "is_test": true
    }
  ]
}
}
```

## Deleting a webhook subscription

To delete a webhook subscription, make a DELETE request to the webhook endpoint with the object ID of your webhook `https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>`.

```shell cURL theme={null}
curl --location --request DELETE 'https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw ''
```

This returns no body but will return a successful **2XX** status.


# Tracking
Source: https://docs.goshippo.com/tracking/tracking

Track shipments across all carriers with normalized data, real-time webhook updates, and complete tracking history.

Use the Shippo Tracking API to track shipments from all carriers with normalized data, complete tracking history, and real-time updates. When used with webhooks, you'll receive instant notifications whenever there's a tracking update. This setup ensures you always have the latest tracking information for all your shipments and can alert recipients if they need to take action.

## Track live shipments

If you have already created a webhook, labels purchased through Shippo will send tracking events to that webhook.

If you did not purchase a label through Shippo and would like to receive tracking updates on your webhook you can register the tracking number with the following example using a tracking number and the name of the carrier.

<Info>
  **Note**

  To use live tracking, you must use your [live key](/guides/authentication). If you want to test tracking with test mode, see the [testing tracking guide](#testing-tracking).
</Info>

1. Create a [webhook](/tracking/webhooks).
   * Set the webhook **Event Type** to **Track Updated**.
   * Set the webhook **Environment** to **Production**.
   * Set the webhook **URL** to an address that can [listen to your webhook](/tracking/webhook-debugging).

<Warning>
  **Important**

  * Tracking webhooks are not idempotent.
  * Clients should register a webhook only once per tracking event.
  * Duplicate registrations can result in multiple notifications for the same event.
</Warning>

2. POST the below to the [tracks endpoint](https://api.goshippo.com/tracks/).

```shell theme={null}
curl https://api.goshippo.com/tracks/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -d carrier="usps" \
  -d tracking_number="9102969010383081813033" \
  -d metadata="Order 000123"
```

You must register a webhook prior to POSTing to the tracking endpoint. Once POSTed, all updates to that tracking number will only be sent to your active tracking webhooks.

You can find a [list of all supported carrier tokens here.](/api-reference/track) Also, certain carriers require an account to track shipments sent through them or only permit tracking shipments created through Shippo. Please see [Carrier Restrictions](/tracking/tracking#carrier-restrictions) below for details.

You will get a response back that includes the latest tracking status via the corresponding `tracking_status` field, and the entire history via the `tracking_history` field, see a sample response below. Tracking is included for shipments created on Shippo but incurs a cost per tracking number for all other shipments.

```json theme={null}
{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "original_eta": "2023-07-23T00:00:00Z",
  "eta": "2023-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2023-07-23T20:35:26.129Z",
    "object_updated": "2023-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2023-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2023-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2023-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2023-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2023-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}
```

## Event definitions

The returned response from a tracking request includes a `status`. The `status` is a high-level indication  of where in the delivery process your package is.
Below is a list of possible `status` values with a description of each.

| Status        | Description                                                                                                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PRE_TRANSIT` | The label is created but before the package is dropped off or picked up by the carrier.                                                                                                                |
| `TRANSIT`     | The package has been scanned by the carrier and is in transit.                                                                                                                                         |
| `DELIVERED`   | The package has been successfully delivered.                                                                                                                                                           |
| `RETURNED`    | The package is en route to be returned to the sender, or has been returned successfully.                                                                                                               |
| `FAILURE`     | The carrier indicated that there has been an issue with the delivery. This can happen for various reasons and depends on the carrier. This status does not indicate a technical, but a delivery issue. |
| `UNKNOWN`     | The package has not been found via the carrier's tracking system.                                                                                                                                      |

Each `status` may also have a `substatus`. A `substatus` can give finer details about the current status of your package. Each field's definition is also available in our [API Reference documentation](/api-reference/tracking-status/get-a-tracking-status).

The `action_required` indicates the `substatus` requires action from the shipper or recipient to complete delivery.

| Status        | Substatus              | Definition                                                                            | Meaning                                                                                                                                                                                                                                                                 | Action Required?               |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `PRE_TRANSIT` | information\_received  | Information about the package received.                                               | The carrier has received the necessary details about your package. This is normally the first step in the shipping process, indicating that the shipment information is in the  carrier's system.                                                                       |                                |
| `TRANSIT`     | address\_issue         | Address information is incorrect. Contact carrier to ensure delivery.                 | There is a problem with the address provided for the delivery. The address may be incorrect or incomplete. You must contact the carrier to correct the address and ensure the package can be delivered.                                                                 | <img alt="green check mark" /> |
| `TRANSIT`     | contact\_carrier       | Contact the carrier for more information.                                             | The carrier needs more additional information or action from you. You should contact the carrier to resolve any issues or get more details about the package status.                                                                                                    | <img alt="green check mark" /> |
| `TRANSIT`     | delayed                | Delivery of package is delayed.                                                       | The delivery of the package is experiencing a delay. This could be due to various reasons such as weather conditions, high shipment volumes, or logistical issues.                                                                                                      |                                |
| `TRANSIT`     | delivery\_attempted    | Delivery of package has been attempted. Contact carrier to ensure delivery.           | The carrier tried to deliver the package but was unsuccessful. This may be due to no one being available to receive it or other access issues. You should contact the carrier to arrange for another delivery attempt.                                                  | <img alt="green check mark" /> |
| `TRANSIT`     | delivery\_rescheduled  | Delivery of package has been rescheduled.                                             | The scheduled delivery date for the package has been changed. This could be due to the recipient's request or other logistical reasons.                                                                                                                                 |                                |
| `TRANSIT`     | delivery\_scheduled    | Package is scheduled for delivery.                                                    | Your package is planned for delivery on a specific date. The carrier has set a delivery date for your package.                                                                                                                                                          |                                |
| `TRANSIT`     | location\_inaccessible | Delivery location inaccessible to carrier. Contact carrier to ensure delivery.        | The delivery location cannot be reached by the carrier. This could be due to physical barriers, restricted access, or other obstacles. You should contact the carrier to resolve the issue and ensure delivery.                                                         | <img alt="green check mark" /> |
| `TRANSIT`     | notice\_left           | Carrier left notice during attempted delivery. Follow carrier instructions on notice. | The carrier left a notice at your address during an attempted delivery. This notice will have instructions on how to receive your package, such as scheduling a redelivery or picking it up from a carrier location.                                                    | <img alt="green check mark" /> |
| `TRANSIT`     | out\_for\_delivery     | Package is out for delivery.                                                          | Your package is currently on its way to the delivery address. This can also mean your package was scanned by a package handler and placed on a pallet to be loaded on a vehicle for delivery. It is with the carrier's delivery personnel and should be delivered soon. |                                |
| `TRANSIT`     | package\_accepted      | Package has been accepted into the carrier network for delivery.                      | The carrier has received your package into their network and it is ready to be processed for delivery                                                                                                                                                                   |                                |
| `TRANSIT`     | package\_arrived       | Package has arrived at an intermediate location in the carrier network.               | Your package has reached a transit point in the carrier's network. This is typically an intermediate facility where packages are sorted and sent to their next destination.                                                                                             |                                |
| `TRANSIT`     | package\_damaged       | Package has been damaged. Contact carrier for more details.                           | Your package has been damaged during the shipping process. You should contact the carrier to get more information and possibly file a claim.                                                                                                                            | <img alt="green check mark" /> |
| `TRANSIT`     | package\_departed      | Package has departed from an intermediate location in the carrier network.            | Your package has left a transit point in the carrier's network and is on its way to the next destination.                                                                                                                                                               |                                |
| `TRANSIT`     | package\_forwarded     | Package has been forwarded.                                                           | Your package has been redirected to a different address. This could be due to a forwarding request by the recipient or an address correction.                                                                                                                           |                                |
| `TRANSIT`     | package\_held          | Package held at carrier location. Contact carrier for more details.                   | The carrier is holding your package at a specific location. You should contact the carrier to find out why it is being held and how to retrieve it.                                                                                                                     |                                |
| `TRANSIT`     | package\_processed     | Package has been processed at an intermediate location.                               | Your package has been processed at a transit point and is ready for the next step in the delivery process.                                                                                                                                                              |                                |
| `TRANSIT`     | package\_processing    | Package is processing at an intermediate location in the carrier network.             | Your package is currently being processed at a transit point. This involves sorting and preparing it for the next leg of its journey.                                                                                                                                   |                                |
| `TRANSIT`     | pickup\_available      | Package is available for pickup at carrier location.                                  | Your package is available for pickup at a carrier location. You can go to the specified location to collect your package.                                                                                                                                               | <img alt="green check mark" /> |
| `TRANSIT`     | reschedule\_delivery   | Contact carrier to reschedule delivery.                                               | You need to contact the carrier to arrange a new delivery date for your package. This might be due to an issue with the initial delivery attempt.                                                                                                                       | <img alt="green check mark" /> |
| `DELIVERED`   | delivered              | Package has been delivered.                                                           | Your package has been successfully delivered to the recipient's address.                                                                                                                                                                                                |                                |
| `RETURNED`    | return\_to\_sender     | Package is to be returned to sender.                                                  | Your package is being sent back to the sender. This could be due to an undeliverable address, refusal by the recipient, or other reasons.                                                                                                                               |                                |
| `RETURNED`    | package\_unclaimed     | Package is unclaimed.                                                                 | Your package has not been claimed by the recipient. You may need to contact the carrier to arrange for collection or redelivery.                                                                                                                                        | <img alt="green check mark" /> |
| `FAILURE`     | package\_undeliverable | Package is not able to be delivered.                                                  | The carrier is unable to deliver your package. This could be due to address issues, recipient unavailability, or other reasons. You should contact the carrier to resolve the issue.                                                                                    | <img alt="green check mark" /> |
| `FAILURE`     | package\_disposed      | Package has been disposed.                                                            | The carrier has disposed of your package. This usually happens when a package is undeliverable and unclaimed for an extended period.                                                                                                                                    |                                |
| `FAILURE`     | package\_lost          | Package has been lost. Contact carrier for more details.                              | Your package has been lost in the shipping process. You should contact the carrier for more details and to possibly file a claim for the lost item.                                                                                                                     | <img alt="green check mark" /> |
| `UNKNOWN`     | other                  | Unrecognized carrier status.                                                          |                                                                                                                                                                                                                                                                         |                                |

***

## Testing tracking

In our Test environment you are able to review our responses with mock tracking numbers. Using your Shippo Test Token, use `shippo` as your `carrier` and the tracking number be one of the following, depending on which tracking event you're testing: `SHIPPO_PRE_TRANSIT`, `SHIPPO_TRANSIT`, `SHIPPO_DELIVERED`, `SHIPPO_RETURNED`, `SHIPPO_FAILURE`, `SHIPPO_UNKNOWN`.

Follow this example.

```shell Test tracking request theme={null}
curl https://api.goshippo.com/tracks/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -d carrier="shippo" \
  -d tracking_number="SHIPPO_TRANSIT" \
  -d metadata="Order 000123"
```

```json Test tracking response theme={null}
{
    "messages": [],
    "carrier": "shippo",
    "tracking_number": "SHIPPO_TRANSIT",
    "address_from": {
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US"
    },
    "address_to": {
        "city": "Chicago",
        "state": "IL",
        "zip": "60611",
        "country": "US"
    },
    "eta": "2018-08-02T18:49:42.566",
    "original_eta": "2018-08-02T18:49:42.566",
    "servicelevel": {
        "token": "shippo_priority",
        "name": "Priority Mail"
    },
    "metadata": "Shippo test tracking",
    "tracking_status": {
        "object_created": "2018-07-30T18:49:42.586",
        "object_updated": null,
        "object_id": "560f1b9cfe8341a2899e0388f1b9081c",
        "status": "TRANSIT",
        "status_details": "Your shipment has departed from the origin.",
        "status_date": "2018-07-29T16:44:42.586",
        "substatus": null,
        "location": {
            "city": "San Francisco",
            "state": "CA",
            "zip": "94103",
            "country": "US"
        }
    },
    "tracking_history": [
        {
            "object_created": "2018-07-30T18:49:42.589",
            "object_updated": null,
            "object_id": "9a056563ad874a0b9bf79dee321f25f5",
            "status": "UNKNOWN",
            "status_details": "The carrier has received the electronic shipment information.",
            "status_date": "2018-07-28T14:39:42.589",
            "substatus": null,
            "location": {
                "city": "San Francisco",
                "state": "CA",
                "zip": "94103",
                "country": "US"
            }
        },
        {
            "object_created": "2018-07-30T18:49:42.589",
            "object_updated": null,
            "object_id": "82ef073b04ef48368e79b835af788fce",
            "status": "TRANSIT",
            "status_details": "Your shipment has departed from the origin.",
            "status_date": "2018-07-29T16:44:42.589",
            "substatus": null,
            "location": {
                "city": "San Francisco",
                "state": "CA",
                "zip": "94103",
                "country": "US"
            }
        }
    ],
    "transaction": null,
    "test": true
}
```

To see all possible status, substatus and corresponding action\_required values, review our [full list](/tracking/tracking#event-definitions) above.

## Track Shippo shipments

For each production label you purchase, Shippo automatically tracks the shipment status through the corresponding carrier's tracking system.

The latest status is accessible via the corresponding Transaction's `tracking_status` field.

Here's a sample Transaction object:

```json theme={null}
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2023-11-29T16:31:19.512Z",
    "object_updated": "2023-11-29T16:31:19.512Z",
    "object_id": "5695ae3a5eda41ba9abdbf347fd545f3",
    "object_owner": "test@shippo.com",
    "test": false,
    "rate": "693ea14a541f44e090291b929c171d5a",
    "tracking_number": "9102969010383081813033",
    "tracking_status": "DELIVERED",
    "eta": "2023-11-24T00:00:00Z",
    "tracking_url_provider": "https:\/\/tools.usps.com\/go\/TrackConfirmAction_input?origTrackNum=9102969010383081813033",
    "label_url": "https:\/\/shippo-delivery-east.s3.amazonaws.com\/5695ae3a5eda41ba9abdbf347fd545f3.pdf?Signature=AyiitLq2g%2F2R9fjboCTVxi5z7JQ%3D&Expires=1534873886&AWSAccessKeyId=AKIAJGLCC5MYLLWIG42A",
    "commercial_invoice_url": null,
    "messages": [],
    "order": "ca760ef0099040b4a2b7feec827bca88",
    "metadata": "",
    "parcel": "e0de043b2f7f4b6d8e6f23ad69641cc1",
    "billing": {"payments": []}
}
```

## Track individual shipments

To submit an individual tracking request for a single shipment, including those created outside of Shippo, you can send a GET request to the [Tracking Status endpoint](/api-reference/tracking-status/get-a-tracking-status) with your shipment `carrier` and `tracking_number`.

You can find a [list of all supported carrier tokens here](/api-reference/track).

Here's a sample request.

```shell theme={null}
curl https://api.goshippo.com/tracks/usps/9205590164917312751089\
    -H "Authorization: ShippoToken <API_TOKEN>"
```

The response is similar to the example above.

***

## Adding metadata

You can add `metadata` to the tracking request through a POST request. This is a free form field where any user-specific information can be added. By making a POST request to add metadata, all your existing webhooks will also be connected to the tracked shipment.

The POST request's body needs to consist of your shipment's `tracking_number` and `carrier`:

```shell theme={null}
curl https://api.goshippo.com/tracks/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d carrier="usps"\
    -d tracking_number="9205590164917312751089"\
    -d metadata="Order 000123"
```

## Including package details

You can include an optional boolean parameter, `include_package_details`, in the tracking POST request. This parameter is currently supported only for UPS and FedEx. If omitted, it defaults to `false`. If set to `true`, Shippo may include `weight` and `dimensions` in the tracking API response when those details are available from the carrier's tracking API. Package details are returned only in the tracking API response; track\_updated webhook payloads do not include `weight` or `dimensions`. Weight and dimensions may be partial and may be updated over time as the carrier provides additional data. Shippo includes only fields provided by the carrier and does not add default or `null` values for missing dimension fields. Dimensions are omitted only when the unit is missing and cannot be safely inferred, or when the carrier-provided data is invalid.

Here's a sample request:

```shell theme={null}
curl https://api.goshippo.com/tracks/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d carrier="ups"\
    -d tracking_number="1Z999AA10123456784"\
    -d include_package_details=true
```

For example, when `include_package_details=true` and the carrier returns package details, the response can include:

```json theme={null}
"weight": [
    {
        "value": "2.2",
        "unit": "LB"
    },
    {
        "value": "1.0",
        "unit": "KG"
    }
],
"dimensions": [
    {
        "length": "1",
        "width": "2",
        "height": "3",
        "unit": "in"
    },
    {
        "length": "3",
        "width": "5",
        "height": "8",
        "unit": "cm"
    }
],
```

## Carrier restrictions

Some carriers require that you have an account with them to track shipments being delivered through them. This is only relevant if you are sending your tracking numbers as a POST to get updates via our webhook (where it is required to have a Shippo account). Otherwise, you simply wouldn't be able to track shipments through the below carriers.

To track shipments with the below carriers, add your respective carrier account into your Shippo account:

* Australia Post
* BetterTrucks
* Correos España
* GLS US
* Gophr
* GSO
* Hongkong Post
* Jitsu
* LSO
* Mondial Relay
* PCF
* Poste Italiane
* Purolator
* Swyft

Additionally, the following carriers only permit tracking shipments that were created though Shippo:

* Canada Post
* Colissimo
* Deutsche Post
* DHL eCommerce
* DHL Germany
* DPD UK
* Evri UK
* Lasership
* New Zealand Post
* Ontrac
* Passport

See [Carrier Accounts](/carriers/carrier-accounts) for details on adding carrier accounts to your Shippo account.

## Tracking pages

Tracking pages let retailers share detailed order tracking information through the native look and feel of their own brand. You can [brand your own tracking pages](https://goshippo.com/blog/tracking-pages/) within the Shippo web app.

1. Log in to our Web app to upload assets to the **Tracking** page in your settings.
2. Publish content and retrieve your base URL from the **View test link** link.
3. Send customers to your pages (include this link in your own emails, for example) with the `<baseurl>/<carrier>/<trackingnumber>`.

By default, your URL may take the following pattern.

`https://track.goshippo.com/tracking/<UserID>/<carrier>/<trackingnumber>`

<img alt="shippo tracking page sample" />


# Tracking carriers using webhooks
Source: https://docs.goshippo.com/tracking/tracking-carrier

View the list of carriers that support webhook-only tracking for parcels shipped outside of Shippo.

If you have already created a webhook, labels purchased through Shippo will send tracking events to that webhook.
Shippo also supports parcel tracking for labels purchased outside of Shippo.

The following list of carriers can only be tracked using webhooks. This means you cannot query the [current status of shipment](/tracking/tracking#track-individual-shipments).
For a list of carriers that support both webhook tracking and polling, review [this list of carriers](/tracking/tracking-carriers).

| Carrier Name                                      | Country Code                               | Region   | Token                                               | URL                                                                                              |
| ------------------------------------------------- | ------------------------------------------ | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 123 Kurier Czech                                  | CZ                                         | Europe   | `123_kurier_czech`                                  | [https://www.123kuryr.cz](https://www.123kuryr.cz)                                               |
| 123 Kurier Slovakia                               | SK                                         | Europe   | `123_kurier_slovakia`                               | [https://123kurier.jpsoftware.sk](https://123kurier.jpsoftware.sk)                               |
| 139 Express                                       | CN                                         | Asia     | `139_express`                                       | [https://www.139express.com](https://www.139express.com)                                         |
| 2660 Express                                      | PT                                         | Europe   | `2660_express`                                      | [https://2660express.pt](https://2660express.pt)                                                 |
| 2GO                                               | PH                                         | Asia     | `2go`                                               | [https://supplychain.2go.com.ph](https://supplychain.2go.com.ph)                                 |
| 360 Lion Express                                  | CN                                         | Asia     | `360_lion_express`                                  | [https://www.360lion.com](https://www.360lion.com)                                               |
| 3JMS Logistics                                    | US                                         | Americas | `3jms_logistics`                                    | [https://tracking.3jmslogistics.com](https://tracking.3jmslogistics.com)                         |
| 4 72 Entregando                                   | CO                                         | Americas | `4_72_entregando`                                   | [https://www.4-72.com.co](https://www.4-72.com.co)                                               |
| 4PX                                               | CN                                         | Asia     | `4px`                                               | [https://express.4px.com](https://express.4px.com)                                               |
| 5post                                             | RU                                         | Europe   | `5post`                                             | [https://fivepost.ru](https://fivepost.ru)                                                       |
| 8express                                          | RU                                         | Europe   | `8express`                                          | [https://8express.ru](https://8express.ru)                                                       |
| 99 Minutos                                        | MX                                         | Americas | `99_minutos`                                        | [https://tracking.99minutos.com](https://tracking.99minutos.com)                                 |
| A Duie Pyle                                       | US                                         | Americas | `a_duie_pyle`                                       | [https://www.aduiepyle.com](https://www.aduiepyle.com)                                           |
| A1Post                                            | BG                                         | Europe   | `a1post`                                            | [https://a1post.bg](https://a1post.bg)                                                           |
| A2B Express Logistics                             | BA                                         | Europe   | `a2b_express_logistics`                             | [https://a2b.ba](https://a2b.ba)                                                                 |
| AAA Cooper Transportation                         | US                                         | Americas | `aaa_cooper_transportation`                         | [https://www.aaacooper.com](https://www.aaacooper.com)                                           |
| AB Custom                                         | ES                                         | Europe   | `ab_custom`                                         | [https://www.abcustom.es](https://www.abcustom.es)                                               |
| ABF Freight                                       | US                                         | Americas | `abf_freight`                                       | [https://arcb.com](https://arcb.com)                                                             |
| aCommerce                                         | SG,TH,ID,PH,MY                             | Asia     | `acommerce`                                         | [https://tracking.acommerce.asia](https://tracking.acommerce.asia)                               |
| ACS Courier                                       | GR                                         | Europe   | `acs_courier`                                       | [https://www.acscourier.net](https://www.acscourier.net)                                         |
| ACS Worldwide Express                             | CN                                         | Asia     | `acs_worldwide_express`                             | [https://acsnets.com.bd](https://acsnets.com.bd)                                                 |
| ADSOne                                            | AU                                         | Oceania  | `adsone`                                            | [https://tracking.icumulus.cloud](https://tracking.icumulus.cloud)                               |
| Aeronet                                           | US                                         | Americas | `aeronet`                                           | [https://www.aeronet.com](https://www.aeronet.com)                                               |
| AEX Shipping                                      | SG                                         | Asia     | `aex_shipping`                                      | [https://portal.aexshipping.com](https://portal.aexshipping.com)                                 |
| Afghan Post                                       | AF                                         | Asia     | `afghan_post`                                       | afghanpost.gov.af                                                                                |
| Agility                                           | KW,CL,PE,KZ,PL,SK,AF,BD,I                  | Asia     | `agility`                                           | [https://tracking.agility.com](https://tracking.agility.com)                                     |
| AIR21                                             | PH                                         | Asia     | `air21`                                             | [https://www.air21.com.ph](https://www.air21.com.ph)                                             |
| AirIndia Cargo                                    | IN                                         | Asia     | `airindia_cargo`                                    | [https://www.airindia.in](https://www.airindia.in)                                               |
| Airpak Express                                    | MY                                         | Asia     | `airpak_express`                                    | [https://tracking.airpak-express.com](https://tracking.airpak-express.com)                       |
| Airspeed International Corporation                | PH                                         | Asia     | `airspeed_international_corporation`                | [https://airspeed.ph](https://airspeed.ph)                                                       |
| Aland Post                                        | AX                                         | Europe   | `aland_post`                                        | [https://www.alandpost.ax](https://www.alandpost.ax)                                             |
| Alas Express                                      | CL                                         | Americas | `alas_express`                                      | [https://www.alasxpress.com](https://www.alasxpress.com)                                         |
| Alaska Cargo                                      | US                                         | Americas | `alaska_cargo`                                      | [https://www.alaskacargo.com](https://www.alaskacargo.com)                                       |
| Albanian Post                                     | AL                                         | Europe   | `albanian_post`                                     | [www.postashqiptare.al](http://www.postashqiptare.al)                                            |
| Algeria Post                                      | DZ                                         | Africa   | `algeria_post`                                      | [www.poste.dz](http://www.poste.dz)                                                              |
| Ali Business Logistics                            | CN                                         | Asia     | `ali_business_logistics`                            | [www.al8856.com](http://www.al8856.com)                                                          |
| AliExpress Standard Shipping                      | CN                                         | Asia     | `aliexpress_standard_shipping`                      | [https://global.cainiao.com](https://global.cainiao.com)                                         |
| ALLJOY SUPPLY CHAIN                               | CN                                         | Asia     | `alljoy_supply_chain`                               | [https://www.alljoylogistics.com](https://www.alljoylogistics.com)                               |
| Alpha fast                                        | TH                                         | Asia     | `alpha_fast`                                        | [https://www.alphafast.com](https://www.alphafast.com)                                           |
| Amazon Shipping DE                                | DE                                         | Europe   | `amazon_shipping_de`                                | [https://www.swiship.de](https://www.swiship.de)                                                 |
| Amazon Shipping India                             | IN                                         | Asia     | `amazon_shipping_india`                             | [https://track.amazon.in](https://track.amazon.in)                                               |
| Amazon Shipping Italy                             | IT                                         | Europe   | `amazon_shipping_italy`                             | [https://track.amazon.it](https://track.amazon.it)                                               |
| Amazon Shipping UK                                | GB                                         | Europe   | `amazon_shipping_uk`                                | [https://track.amazon.co.uk](https://track.amazon.co.uk)                                         |
| Amazon Shipping US                                | US                                         | Americas | `amazon_shipping_us`                                | [https://track.amazon.com](https://track.amazon.com)                                             |
| Amm Spedition                                     | DE                                         | Europe   | `amm_spedition`                                     | [https://tt.amm-spedition.de](https://tt.amm-spedition.de)                                       |
| An Post                                           | IE                                         | Europe   | `an_post`                                           | [https://www.anpost.com](https://www.anpost.com)                                                 |
| ANDESMAR                                          | ES                                         | Europe   | `andesmar`                                          | [https://www.andesmarcargas.com](https://www.andesmarcargas.com)                                 |
| ANDREANI                                          | ES                                         | Europe   | `andreani`                                          | [https://usuarios.e-andreani.com](https://usuarios.e-andreani.com)                               |
| Anguilla Post                                     | AI                                         | Americas | `anguilla_post`                                     | [www.aps.ai](http://www.aps.ai)                                                                  |
| Anicam Box Express                                | CO                                         | Americas | `anicam_box_express`                                | [https://www.anicambox.com.co](https://www.anicambox.com.co)                                     |
| Anjun Logistics                                   | CN                                         | Asia     | `anjun_logistics`                                   | [https://www.szanjun.com](https://www.szanjun.com)                                               |
| AnserX                                            | CN                                         | Asia     | `anserx`                                            | [https://oms.anserx.com](https://oms.anserx.com)                                                 |
| Antilles Post                                     | NL                                         | Europe   | `antilles_post`                                     | [https://tracking.cpostinternational.com](https://tracking.cpostinternational.com)               |
| APC Overnight                                     | GB                                         | Europe   | `apc_overnight`                                     | [https://www.apc-overnight.com](https://www.apc-overnight.com)                                   |
| APC Postal Logistics                              | CA,US                                      | Americas | `apcpost`                                           | [www.apc-pli.com](http://www.apc-pli.com)                                                        |
| Apex Motor Express                                | CA                                         | Americas | `apex_motor_express`                                | [https://www.apexltl.com](https://www.apexltl.com)                                               |
| APG eCommerce                                     | AU                                         | Oceania  | `apg_ecommerce`                                     | [https://apgecommerce.com](https://apgecommerce.com)                                             |
| Aprisa Express                                    | US                                         | Americas | `aprisa_express`                                    | [https://aprisa.cargotrack.net](https://aprisa.cargotrack.net)                                   |
| Aramex                                            | AE                                         | Asia     | `aramex`                                            | [www.aramex.com](http://www.aramex.com)                                                          |
| Aramex Australia                                  | AU                                         | Oceania  | `aramex_australia`                                  | [https://www.aramex.com.au](https://www.aramex.com.au)                                           |
| Aramex New Zealand                                | NZ                                         | Oceania  | `aramex_new_zealand`                                | [https://www.aramex.co.nz](https://www.aramex.co.nz)                                             |
| Ark Express                                       | AU,MY,CN,SG                                | Asia     | `ark_express`                                       | [https://en.arkexpress.com.au](https://en.arkexpress.com.au)                                     |
| Aruba Post                                        | AW                                         | Americas | `aruba_post`                                        | [https://cds.postaruba.com](https://cds.postaruba.com)                                           |
| Ascension Island Post                             | GB                                         | Europe   | `ascension_island_post`                             | [www.ascension-island.gov.ac](http://www.ascension-island.gov.ac)                                |
| ASE KARGO                                         | TR,AZ,KZ                                   | Asia     | `ase_kargo`                                         | [https://tracking.ase.com.tr](https://tracking.ase.com.tr)                                       |
| Asendia Germany                                   | DE                                         | Europe   | `asendia_germany`                                   | [https://www.asendia.de](https://www.asendia.de)                                                 |
| Asendia HK Premium Service                        | HK                                         | Asia     | `asendia_hk_premium_service`                        | [https://www.asendia.hk](https://www.asendia.hk)                                                 |
| Asendia Hong Kong                                 | HK                                         | Asia     | `asendia_hong_kong`                                 | [https://tracking.asendia.com](https://tracking.asendia.com)                                     |
| Asendia UK                                        | GB                                         | Europe   | `asendia_uk`                                        | [https://uktracking.asendia.com](https://uktracking.asendia.com)                                 |
| Asendia USA                                       | US                                         | Americas | `asendia_us`                                        | [https://www.asendiausa.com/](https://www.asendiausa.com/)                                       |
| ASIGNA                                            | MX                                         | Americas | `asigna`                                            | [https://web.asigna.es](https://web.asigna.es)                                                   |
| ASL Distribution Services                         | CA                                         | Americas | `asl_distribution_services`                         | [https://ng-amz.shiptrackapp.com](https://ng-amz.shiptrackapp.com)                               |
| ASP Express                                       | ID                                         | Asia     | `asp_express`                                       | [https://ongkir.aspxpress.com](https://ongkir.aspxpress.com)                                     |
| Asus International Logistics                      | CN                                         | Asia     | `asus_international_logistics`                      | [https://www.kuaidi586.com](https://www.kuaidi586.com)                                           |
| AuExpress                                         | AU,CN                                      | Asia     | `auexpress`                                         | [https://www.auexpress.com](https://www.auexpress.com)                                           |
| AuPost China                                      | CN                                         | Asia     | `aupost_china`                                      | [https://www.aupost.org](https://www.aupost.org)                                                 |
| Australia Post                                    | AU                                         | Oceania  | `australia_post`                                    | [www.auspost.com.au](http://www.auspost.com.au)                                                  |
| Avante Logistic                                   | ES                                         | Europe   | `avante_logistic`                                   | [https://avantelogistics.ec](https://avantelogistics.ec)                                         |
| Averitt Express                                   | US                                         | Americas | `averitt_express`                                   | [https://tools.averitt.com](https://tools.averitt.com)                                           |
| Axlehire                                          | US                                         | Americas | `axlehire`                                          | [https://axlehire.com/](https://axlehire.com/)                                                   |
| Azer Express Post                                 | AZ                                         | Asia     | `azer_express_post`                                 | [www.azems.az](http://www.azems.az)                                                              |
| Azerbaijan Post                                   | AZ                                         | Asia     | `azerbaijan_post`                                   | [https://www.azerpost.az](https://www.azerpost.az)                                               |
| B2C Europe                                        | FR,NL,ES,GB                                | Europe   | `b2c_europe`                                        | [https://trackyourparcel.eu](https://trackyourparcel.eu)                                         |
| Bahamas Post                                      | BS                                         | Americas | `bahamas_post`                                      | [www.bahamas.gov.bs](http://www.bahamas.gov.bs)                                                  |
| Bahrain Post                                      | BH                                         | Asia     | `bahrain_post`                                      | [www.bahrain.bh](http://www.bahrain.bh)                                                          |
| Baikalsr                                          | RU                                         | Europe   | `baikalsr`                                          | [https://www.baikalsr.ru](https://www.baikalsr.ru)                                               |
| Bangladesh Post                                   | BD                                         | Asia     | `bangladesh_post`                                   | [www.bangladeshpost.gov.bd](http://www.bangladeshpost.gov.bd)                                    |
| Barbados Post                                     | BB                                         | Americas | `barbados_post`                                     | [www.bps.gov.bb](http://www.bps.gov.bb)                                                          |
| BDMnet                                            | IT                                         | Europe   | `bdmnet`                                            | [https://www.bdmnet.it](https://www.bdmnet.it)                                                   |
| Bel Logistics                                     | CN                                         | Asia     | `bel_logistics`                                     | [https://8256.kingtrans.cn](https://8256.kingtrans.cn)                                           |
| Belize Post                                       | BZ                                         | Americas | `belize_post`                                       | [www.belizepostalservice.gov.bz](http://www.belizepostalservice.gov.bz)                          |
| Belpost                                           | BY                                         | Europe   | `belpost`                                           | [https://www.belpost.by](https://www.belpost.by)                                                 |
| Beone Logistics                                   | AE                                         | Asia     | `beone_logistics`                                   | [https://ibeone.com](https://ibeone.com)                                                         |
| Bermuda Post                                      | BM                                         | Americas | `bermuda_post`                                      | [https://www.bpo.bm](https://www.bpo.bm)                                                         |
| Bert Transport                                    | FR                                         | Europe   | `bert_transport`                                    | [https://bert.fr](https://bert.fr)                                                               |
| Best Express                                      | CN                                         | Asia     | `best_express`                                      | [https://www.800bestex.com](https://www.800bestex.com)                                           |
| Bhutan Post Domestic                              | BT                                         | Asia     | `bhutan_post_domestic`                              | [https://www.bhutanpost.bt](https://www.bhutanpost.bt)                                           |
| Bird System                                       | CN,GB                                      | Asia     | `bird_system`                                       | [https://www.birdsystem.co.uk](https://www.birdsystem.co.uk)                                     |
| Black Arrow Express                               | PH                                         | Asia     | `black_arrow_express`                               | [https://locator.blackarrow.express](https://locator.blackarrow.express)                         |
| BLUE EXPRESS                                      | ES                                         | Europe   | `blue_express`                                      | [https://www.bluex.cl](https://www.bluex.cl)                                                     |
| Blue Streak Couriers                              | US                                         | Americas | `blue_streak_couriers`                              | [https://bluestreak.cc](https://bluestreak.cc)                                                   |
| Bluecare Express                                  | US                                         | Americas | `bluecare_express`                                  | [https://bluecare.express](https://bluecare.express)                                             |
| Bluedart                                          | IN                                         | Asia     | `bluedart`                                          | [https://www.bluedart.com](https://www.bluedart.com)                                             |
| Bombino Express                                   | IN                                         | Asia     | `bombino_express`                                   | [https://www.bombinoexp.com](https://www.bombinoexp.com)                                         |
| Bonds Couriers                                    | AU                                         | Oceania  | `bonds_couriers`                                    | [https://www.bondscouriers.com.au](https://www.bondscouriers.com.au)                             |
| Boo Kurier                                        | RO                                         | Europe   | `boo_kurier`                                        | [https://www.bookurier.ro](https://www.bookurier.ro)                                             |
| Border Express                                    | AU                                         | Oceania  | `border_express`                                    | [https://www.borderexpress.com.au](https://www.borderexpress.com.au)                             |
| Botswana Post                                     | BW                                         | Africa   | `botswana_post`                                     | [https://posttracking.botswanapost.co.bw](https://posttracking.botswanapost.co.bw)               |
| BOXC                                              | CN                                         | Asia     | `boxc`                                              | [https://www.boxc.com](https://www.boxc.com)                                                     |
| Boxtal                                            | FR                                         | Europe   | `boxtal`                                            | [https://www.boxtal.com](https://www.boxtal.com)                                                 |
| BQC                                               | CN                                         | Asia     | `bqc`                                               | [https://www.bqcdz.com](https://www.bqcdz.com)                                                   |
| Brunei Post                                       | BN                                         | Asia     | `brunei_post`                                       | [www.post.gov.bn](http://www.post.gov.bn)                                                        |
| Buffalo International Logistics                   | CN                                         | Asia     | `buffalo_international_logistics`                   | [https://index.buffaloex.com](https://index.buffaloex.com)                                       |
| Bulgarian Post                                    | BG                                         | Europe   | `bulgarian_post`                                    | [https://www.bgpost.bg](https://www.bgpost.bg)                                                   |
| Burd Delivery                                     | DK                                         | Europe   | `burd_delivery`                                     | [https://burd.dk](https://burd.dk)                                                               |
| Burundi Post                                      | BI                                         | Africa   | `burundi_post`                                      | [www.poste.bi](http://www.poste.bi)                                                              |
| Buy Logic                                         | CN                                         | Asia     | `buy_logic`                                         | [https://www.buylogic.cc](https://www.buylogic.cc)                                               |
| C807 Express SV                                   | SV                                         | Americas | `c807_express_sv`                                   | [https://c807xpress.com](https://c807xpress.com)                                                 |
| Cacesa                                            | ES                                         | Europe   | `cacesa`                                            | [https://www.cacesapostal.com](https://www.cacesapostal.com)                                     |
| Cainiao                                           | CN                                         | Asia     | `cainiao`                                           | [https://global.cainiao.com](https://global.cainiao.com)                                         |
| Cambodia Post                                     | KH                                         | Asia     | `cambodia_post`                                     | [https://www.ems.com.kh](https://www.ems.com.kh)                                                 |
| Campost                                           | CM                                         | Africa   | `campost`                                           | [https://tracking.campost.cm](https://tracking.campost.cm)                                       |
| Canpar Courier                                    | CA                                         | Americas | `canpar_courier`                                    | [https://www.canpar.ca](https://www.canpar.ca)                                                   |
| Cargo Expreso GT                                  | GT                                         | Americas | `cargo_expreso_gt`                                  | [https://www.cargoexpreso.com](https://www.cargoexpreso.com)                                     |
| Cargo Expreso SV                                  | SV                                         | Americas | `cargo_expreso_sv`                                  | [https://www.cargoexpreso.com](https://www.cargoexpreso.com)                                     |
| Cargo International                               | DE                                         | Europe   | `cargo_international`                               | [https://www.cargointernational.de](https://www.cargointernational.de)                           |
| CARRIYO                                           | US                                         | Americas | `carriyo`                                           | [https://carriyo.io](https://carriyo.io)                                                         |
| Carry Flap                                        | JP                                         | Asia     | `carry_flap`                                        | [https://carry-flap.com](https://carry-flap.com)                                                 |
| Cayman Islands Post                               | GB                                         | Europe   | `cayman_islands_post`                               | [www.caymanpost.gov.ky](http://www.caymanpost.gov.ky)                                            |
| CBL Logistics                                     | ES                                         | Europe   | `cbl_logistics`                                     | [https://www.cbl-logistica.com](https://www.cbl-logistica.com)                                   |
| CDEK                                              | DE                                         | Europe   | `cdek`                                              | [https://www.cdek.ru](https://www.cdek.ru)                                                       |
| Celeritas                                         | ES                                         | Europe   | `celeritas`                                         | [https://celeritastransporte.com](https://celeritastransporte.com)                               |
| Central Transport                                 | MX,CA,US                                   | Americas | `central_transport`                                 | [https://www.centraltransportint.com](https://www.centraltransportint.com)                       |
| Czech Post                                        | CZ                                         | Europe   | `czech_post`                                        | [https://www.postaonline.cz](https://www.postaonline.cz)                                         |
| CEVA Logistics                                    | CH                                         | Europe   | `ceva_logistics`                                    | [https://www.cevalogistics.com](https://www.cevalogistics.com)                                   |
| CGS Express                                       | CN                                         | Asia     | `cgs_express`                                       | [https://cgs-express.com](https://cgs-express.com)                                               |
| Chile Fletes                                      | CL                                         | Americas | `chile_fletes`                                      | [https://livetracking.simpliroute.com](https://livetracking.simpliroute.com)                     |
| China EMS                                         | CN                                         | Asia     | `china_ems`                                         | [https://www.ems.com.cn](https://www.ems.com.cn)                                                 |
| China Post                                        | CN                                         | Asia     | `china_post`                                        | [https://www.chinapost.com.cn](https://www.chinapost.com.cn)                                     |
| Chit Chats                                        | CA                                         | Americas | `chit_chats`                                        | [https://chitchats.com](https://chitchats.com)                                                   |
| Choir Express Indonesia                           | ID                                         | Asia     | `choir_express_indonesia`                           | [https://choirexpress.co.id](https://choirexpress.co.id)                                         |
| Chukou1                                           | CN                                         | Asia     | `chukou1`                                           | [https://www.chukou1.com](https://www.chukou1.com)                                               |
| Post Taiwan                                       | TW                                         | Asia     | `post_taiwan`                                       | [https://www.post.gov.tw](https://www.post.gov.tw)                                               |
| City Link Express                                 | MY                                         | Asia     | `city_link_express`                                 | [https://www.citylinkexpress.com](https://www.citylinkexpress.com)                               |
| CJ Century                                        | MY                                         | Asia     | `cj_century`                                        | [https://www.cjlogistics.com](https://www.cjlogistics.com)                                       |
| CJ Korea Express Thailand                         | TH                                         | Asia     | `korea_express_thailand`                            | [www.cjkoreaexpress.com](http://www.cjkoreaexpress.com)                                          |
| CJ Packet                                         | CN                                         | Asia     | `cj_packet`                                         | [https://cjpacket.com](https://cjpacket.com)                                                     |
| CND Express                                       | CN                                         | Asia     | `cnd_express`                                       | [https://www.cndexpress.com](https://www.cndexpress.com)                                         |
| CNE Express                                       | CN                                         | Asia     | `cne_express`                                       | [https://aitrack.com](https://aitrack.com)                                                       |
| CollectCo                                         | MY                                         | Asia     | `collectco`                                         | [https://send.collectco.my](https://send.collectco.my)                                           |
| Collivery                                         | ZA                                         | Africa   | `collivery`                                         | [https://collivery.net](https://collivery.net)                                                   |
| ComOne Express                                    | CN                                         | Asia     | `comone_express`                                    | [https://com1express.net](https://com1express.net)                                               |
| Concise                                           | US                                         | Americas | `concise`                                           | [https://www.concisetrack.com](https://www.concisetrack.com)                                     |
| Conexpress Logistics                              | CO                                         | Americas | `conexpress_logistics`                              | [https://conexpresslogistics.co](https://conexpresslogistics.co)                                 |
| Coordinadora                                      | CO                                         | Americas | `coordinadora`                                      | [https://www.coordinadora.com](https://www.coordinadora.com)                                     |
| Copa Airlines Courier                             | BR                                         | Americas | `copa_airlines_courier`                             | [https://www.copacourier.com](https://www.copacourier.com)                                       |
| COPE Sensitive Freight                            | AU                                         | Oceania  | `cope_sensitive_freight`                            | [https://www.cope.com.au](https://www.cope.com.au)                                               |
| Correios Cabo Verde                               | CV                                         | Africa   | `correios_cabo_verde`                               | [https://correios.cv](https://correios.cv)                                                       |
| Correios de Angola                                | AO                                         | Africa   | `correios_de_angola`                                | [www.correiosdeangola.co.ao](http://www.correiosdeangola.co.ao)                                  |
| Correios de Mozambique                            | MZ                                         | Africa   | `correios_de_mozambique`                            | [www.correios.co.mz](http://www.correios.co.mz)                                                  |
| Correo Argentino                                  | AR                                         | Americas | `correo_argentino`                                  | [https://www.correoargentino.com.ar](https://www.correoargentino.com.ar)                         |
| Correo El Salvador                                | SV                                         | Americas | `correo_el_salvador`                                | [www.correos.gob.sv](http://www.correos.gob.sv)                                                  |
| Correo Honduras                                   | HN                                         | Americas | `correo_honduras`                                   | [www.honducor.gob.hn](http://www.honducor.gob.hn)                                                |
| Correo Panama                                     | PA                                         | Americas | `correo_panama`                                     | [www.correospanama.gob.pa](http://www.correospanama.gob.pa)                                      |
| Correo Paraguayo                                  | PY                                         | Americas | `correo_paraguayo`                                  | [www.correoparaguayo.gov.py](http://www.correoparaguayo.gov.py)                                  |
| Correo Uruguay                                    | UY                                         | Americas | `correo_uruguay`                                    | [www.correo.com.uy](http://www.correo.com.uy)                                                    |
| Correos Bolivia                                   | BO                                         | Americas | `correos_bolivia`                                   | [https://www.correos.gob.bo](https://www.correos.gob.bo)                                         |
| Correos Chile                                     | CL                                         | Americas | `correos_chile`                                     | [https://www.correos.cl](https://www.correos.cl)                                                 |
| Correos Costa Rica                                | CR                                         | Americas | `correos_costa_rica`                                | [www.correos.go.cr](http://www.correos.go.cr)                                                    |
| Correos de Espana                                 | ES                                         | Europe   | `correos_espana`                                    | [https://www.correos.es](https://www.correos.es)                                                 |
| Correos de Mexico                                 | MX                                         | Americas | `correos_de_mexico`                                 | [https://www.correosdemexico.gob.mx](https://www.correosdemexico.gob.mx)                         |
| Correos Ecuador                                   | EC                                         | Americas | `correos_ecuador`                                   | [https://www.correosdelecuador.gob.ec](https://www.correosdelecuador.gob.ec)                     |
| Correos Express                                   | ES                                         | Europe   | `correos_express`                                   | [https://s.correosexpress.com](https://s.correosexpress.com)                                     |
| Correos Guatemala                                 | GT                                         | Americas | `correos_guatemala`                                 | [https://www.correosytelegrafos.civ.gob.gt](https://www.correosytelegrafos.civ.gob.gt)           |
| Cosmetics Now                                     | HK                                         | Asia     | `cosmetics_now`                                     | [https://sg.cosmeticsnow.com](https://sg.cosmeticsnow.com)                                       |
| Courier IT                                        | ZA                                         | Africa   | `courier_it`                                        | [https://www.courierit.co.za](https://www.courierit.co.za)                                       |
| Courier Plus                                      | NG                                         | Africa   | `courier_plus`                                      | [https://www.courierplus-ng.com](https://www.courierplus-ng.com)                                 |
| CourierPost                                       | NZ                                         | Oceania  | `courierpost`                                       | [https://www.nzpost.co.nz](https://www.nzpost.co.nz)                                             |
| CRL Express                                       | AU                                         | Oceania  | `crl_express`                                       | [https://www.crlexpress.com](https://www.crlexpress.com)                                         |
| Cross border                                      | CN                                         | Asia     | `cross_border`                                      | [www.runteck.com](http://www.runteck.com)                                                        |
| CSE                                               | RU                                         | Europe   | `cse`                                               | [https://www.cse.ru](https://www.cse.ru)                                                         |
| CTC Express                                       | TW                                         | Asia     | `ctc_express`                                       | [https://ctc-express.com.tw](https://ctc-express.com.tw)                                         |
| CTM Express                                       | CN,TH                                      | Asia     | `ctm_express`                                       | [https://www.ctmexpress.com](https://www.ctmexpress.com)                                         |
| CTT Express                                       | ES                                         | Europe   | `ctt_express`                                       | [https://www.cttexpress.com](https://www.cttexpress.com)                                         |
| CTT Portugal                                      | PT                                         | Europe   | `ctt_portugal`                                      | [https://www.ctt.pt](https://www.ctt.pt)                                                         |
| Cubyn                                             | FR                                         | Europe   | `cubyn`                                             | [https://track.cubyn.com](https://track.cubyn.com)                                               |
| Cuckoo Express                                    | CN                                         | Asia     | `cuckoo_express`                                    | [https://www.cuckooexpress.com](https://www.cuckooexpress.com)                                   |
| Cyprus Post                                       | CY                                         | Asia     | `cyprus_post`                                       | [https://www.cypruspost.post](https://www.cypruspost.post)                                       |
| DACHSER                                           | DE                                         | Europe   | `dachser`                                           | [https://elogistics.dachser.com](https://elogistics.dachser.com)                                 |
| DAI Post                                          | AU                                         | Oceania  | `dai_post`                                          | [https://www.daipost.com](https://www.daipost.com)                                               |
| Danniao                                           | CN                                         | Asia     | `danniao`                                           | [https://www.danniao.com](https://www.danniao.com)                                               |
| Danske Fragtmaend                                 | DK                                         | Europe   | `danske_fragtmaend`                                 | [https://trace.fragt.dk](https://trace.fragt.dk)                                                 |
| DAO                                               | DK                                         | Europe   | `dao`                                               | [https://www.dao.as](https://www.dao.as)                                                         |
| Day and Ross                                      | US                                         | Americas | `day_and_ross`                                      | [https://dayross.com](https://dayross.com)                                                       |
| Daylight Transport                                | US                                         | Americas | `daylight_transport`                                | [https://www.dylt.com](https://www.dylt.com)                                                     |
| Dayton Freight                                    | US                                         | Americas | `dayton_freight`                                    | [https://tools.daytonfreight.com](https://tools.daytonfreight.com)                               |
| DB Schenker                                       | SE                                         | Europe   | `db_schenker`                                       | [https://eschenker.dbschenker.com](https://eschenker.dbschenker.com)                             |
| DD Express                                        | MY                                         | Asia     | `dd_express`                                        | [https://tracking.dd.express](https://tracking.dd.express)                                       |
| DealerSend                                        | HK                                         | Asia     | `dealersend`                                        | [https://www.dealer-send.com](https://www.dealer-send.com)                                       |
| Delcart                                           | IN                                         | Asia     | `delcart`                                           | [https://www.delcart.in](https://www.delcart.in)                                                 |
| Deliver it                                        | US                                         | Americas | `deliver_it`                                        | [https://www.deliver-it.com](https://www.deliver-it.com)                                         |
| Delnext                                           | PT                                         | Europe   | `delnext`                                           | [https://www.delnext.com](https://www.delnext.com)                                               |
| Deltec Courier                                    | GB                                         | Europe   | `deltec_courier`                                    | [https://www.deltec-courier.com](https://www.deltec-courier.com)                                 |
| DemandShip                                        | US                                         | Americas | `demandship`                                        | [https://demandship.com](https://demandship.com)                                                 |
| Dependable Supply Chain Services                  | US                                         | Americas | `dependable_supply_chain_services`                  | [https://portal.godependable.com](https://portal.godependable.com)                               |
| Deprisa                                           | ES                                         | Europe   | `deprisa`                                           | [https://www.deprisa.com](https://www.deprisa.com)                                               |
| Destinations Express                              | CN                                         | Asia     | `destinations_express`                              | [https://www.dex-i.com](https://www.dex-i.com)                                                   |
| Detrack                                           | SG                                         | Asia     | `detrack`                                           | [https://www.detrack.com](https://www.detrack.com)                                               |
| DEX Bolivia                                       | BO                                         | Americas | `dex_bolivia`                                       | [https://www.dexbolivia.com](https://www.dexbolivia.com)                                         |
| DHL 2 Mann Handling                               | IE                                         | Europe   | `dhl_two_man_handling`                              | [https://www.dhl.de](https://www.dhl.de)                                                         |
| DHL Active Tracing                                | DE                                         | Europe   | `dhl_active_tracing`                                | [https://activetracing.dhl.com](https://activetracing.dhl.com)                                   |
| DHL Benelux                                       | NL,BE,LU                                   | Europe   | `dhl_benelux`                                       | [www.dhl.nl](http://www.dhl.nl)                                                                  |
| DHL eCommerce Vietnam                             | VN                                         | Asia     | `dhl_ecommerce_vietnam`                             | [https://ecommerceportal.dhl.com](https://ecommerceportal.dhl.com)                               |
| DHL Global Forwarding                             | DE                                         | Europe   | `dhl_global_forwarding`                             | [https://dhli.dhl.com](https://dhli.dhl.com)                                                     |
| DHL Hong Kong                                     | HK                                         | Asia     | `dhl_hong_kong`                                     | [https://www.dhl.com.hk](https://www.dhl.com.hk)                                                 |
| DHL Paket                                         | DE                                         | Europe   | `dhl_paket`                                         | [https://www.dhl.de](https://www.dhl.de)                                                         |
| DHL Parcel Netherlands                            | NL                                         | Europe   | `dhl_parcel_netherlands`                            | [https://my.dhlparcel.nl](https://my.dhlparcel.nl)                                               |
| DHL Poland                                        | PL                                         | Europe   | `dhl_poland`                                        | [https://www.dhl.com](https://www.dhl.com)                                                       |
| DHL Spain                                         | ES                                         | Europe   | `dhl_spain`                                         | [https://clientesparcel.dhl.es](https://clientesparcel.dhl.es)                                   |
| DHL Sweden                                        | SE                                         | Europe   | `dhl_sweden`                                        | [https://www.dhl.com](https://www.dhl.com)                                                       |
| Dimerco                                           | TW                                         | Asia     | `dimerco`                                           | [https://home.dimerco.com](https://home.dimerco.com)                                             |
| Direct Link                                       | SE                                         | Europe   | `direct_link`                                       | [https://www.directlink.com](https://www.directlink.com)                                         |
| Direx                                             | BG                                         | Europe   | `direx`                                             | [https://direx.bg](https://direx.bg)                                                             |
| DMSMatrix                                         | GB                                         | Europe   | `dmsmatrix`                                         | [https://dmsmatrix.net](https://dmsmatrix.net)                                                   |
| DocketHUB                                         | GB                                         | Europe   | `dockethub`                                         | [https://tracking.dockethub.com](https://tracking.dockethub.com)                                 |
| Dominica Post                                     | DM                                         | Americas | `dominica_post`                                     | publicworks.gov.dm                                                                               |
| Doora Logistics                                   | KR                                         | Asia     | `doora_logistics`                                   | [https://www.doora.co.kr](https://www.doora.co.kr)                                               |
| Dotzot                                            | IN                                         | Asia     | `dotzot`                                            | [https://dotzot.in](https://dotzot.in)                                                           |
| DPD Austria                                       | AT                                         | Europe   | `dpd_austria`                                       | [https://www.mydpd.at](https://www.mydpd.at)                                                     |
| DPD Belgium                                       | BE                                         | Europe   | `dpd_belgium`                                       | [https://tracking.dpd.de](https://tracking.dpd.de)                                               |
| DPD Hungary                                       | HU                                         | Europe   | `dpd_hungary`                                       | [https://www.dpdgroup.com](https://www.dpdgroup.com)                                             |
| DPD Ireland                                       | IE                                         | Europe   | `dpd_ireland`                                       | [https://dpd.ie](https://dpd.ie)                                                                 |
| DPD Laser                                         | ZA                                         | Africa   | `dpd_laser`                                         | [https://www.dawnwing.co.za](https://www.dawnwing.co.za)                                         |
| DPD Local                                         | GB                                         | Europe   | `dpd_local`                                         | [https://www.dpdlocal-online.co.uk](https://www.dpdlocal-online.co.uk)                           |
| DPD Poland                                        | PL                                         | Europe   | `dpd_poland`                                        | [https://tracktrace.dpd.com.pl](https://tracktrace.dpd.com.pl)                                   |
| DPD Portugal                                      | PT                                         | Europe   | `dpd_portugal`                                      | [https://tracking.dpd.pt](https://tracking.dpd.pt)                                               |
| DPD Romania                                       | RO                                         | Europe   | `dpd_romania`                                       | [https://tracking.dpd.ro](https://tracking.dpd.ro)                                               |
| DPD Russia                                        | RU                                         | Europe   | `dpd_russia`                                        | [https://www.dpd.ru](https://www.dpd.ru)                                                         |
| DPD Switzerland                                   | CH                                         | Europe   | `dpd_switzerland`                                   | [https://tracking.dpd.de](https://tracking.dpd.de)                                               |
| DPD Worldwide                                     | BE,FR,IE,PL,PT,RO,RU,CH                    | Europe   | `dpd_worldwide`                                     | [https://tracking.dpd.de](https://tracking.dpd.de)                                               |
| DPE Express                                       | CN                                         | Asia     | `dpe_express`                                       | [https://www.dpe.net.cn](https://www.dpe.net.cn)                                                 |
| DPE South Africa                                  | ZA                                         | Africa   | `dpe_south_africa`                                  | [https://www.dpe.co.za](https://www.dpe.co.za)                                                   |
| DPEX                                              | HK,SG                                      | Asia     | `dpex`                                              | [https://dpex.com](https://dpex.com)                                                             |
| DPEX China                                        | CN                                         | Asia     | `dpex_china`                                        | [https://www.dpex.com](https://www.dpex.com)                                                     |
| DropIt                                            | MY                                         | Asia     | `dropit`                                            | [https://www.dropit.my](https://www.dropit.my)                                                   |
| Dropp Delivery                                    | DE                                         | Europe   | `dropp_delivery`                                    | [https://schedule.withdropp.com](https://schedule.withdropp.com)                                 |
| DSV                                               | US                                         | Americas | `dsv`                                               | [https://mydsv.com](https://mydsv.com)                                                           |
| DTD Express                                       | MX                                         | Americas | `dtd_express`                                       | [https://dtddirect.com](https://dtddirect.com)                                                   |
| DTDC Australia                                    | AU                                         | Oceania  | `dtdc_australia`                                    | [https://www.dtdcaustralia.com.au](https://www.dtdcaustralia.com.au)                             |
| DTDC India                                        | IN                                         | Asia     | `dtdc_india`                                        | [https://dtdc.com](https://dtdc.com)                                                             |
| Deutsche Textil Logistik                          | DE                                         | Europe   | `dtl`                                               | [www.dtl.de](http://www.dtl.de)                                                                  |
| DWZ International Logistics                       | CN                                         | Asia     | `dwz_international_logistics`                       | [https://www.dwz56.com](https://www.dwz56.com)                                                   |
| Dynalogic                                         | NL                                         | Europe   | `dynalogic`                                         | [https://trackentrace.dynalogic.eu](https://trackentrace.dynalogic.eu)                           |
| Dynamex                                           | CA                                         | Americas | `dynamex`                                           | [https://www.dynamex.com](https://www.dynamex.com)                                               |
| Dynamic Logistics                                 | TH                                         | Asia     | `dynamic_logistics`                                 | [https://www.dynamiclogistics.com](https://www.dynamiclogistics.com)                             |
| E Go                                              | AU                                         | Oceania  | `e_go`                                              | [https://www.e-go.com.au](https://www.e-go.com.au)                                               |
| EAE                                               | CN                                         | Asia     | `eae`                                               | [https://www.eaexp.com](https://www.eaexp.com)                                                   |
| Early Bird                                        | SE                                         | Europe   | `early_bird`                                        | [https://earlybird.delivery](https://earlybird.delivery)                                         |
| Easy Mail                                         | GR                                         | Europe   | `easy_mail`                                         | [https://easy-mail.gr](https://easy-mail.gr)                                                     |
| EC Express                                        | CN                                         | Asia     | `ec_express`                                        | [https://www.ecexpress.com.cn](https://www.ecexpress.com.cn)                                     |
| EC Firstclass                                     | CN                                         | Asia     | `ec_firstclass`                                     | [https://www.ec-firstclass.org](https://www.ec-firstclass.org)                                   |
| Ecargo                                            | KR                                         | Asia     | `ecargo`                                            | [https://ecargo.asia](https://ecargo.asia)                                                       |
| Echo                                              | US                                         | Americas | `echo`                                              | [https://echo.com](https://echo.com)                                                             |
| ECMS Express                                      | US                                         | Americas | `ecms_express`                                      | [https://www.ecmsglobal.com](https://www.ecmsglobal.com)                                         |
| Ecom Express                                      | IN                                         | Asia     | `ecom_express`                                      | [https://www.ecomexpress.in](https://www.ecomexpress.in)                                         |
| Econt                                             | BG                                         | Europe   | `econt`                                             | [https://www.econt.com](https://www.econt.com)                                                   |
| EFS                                               | KR                                         | Asia     | `efs`                                               | [https://web.efs.asia](https://web.efs.asia)                                                     |
| Egypt Post                                        | EG                                         | Africa   | `egypt_post`                                        | [www.egyptpost.org](http://www.egyptpost.org)                                                    |
| Ekart Logistics                                   | IN                                         | Asia     | `ekart_logistics`                                   | [https://www.ekartlogistics.com](https://www.ekartlogistics.com)                                 |
| ELTA Hellenic Post                                | GR                                         | Europe   | `elta_hellenic_post`                                | [https://www.elta-courier.gr](https://www.elta-courier.gr)                                       |
| Emirates Post                                     | AE                                         | Asia     | `emirates_post`                                     | [https://www.emiratespost.ae](https://www.emiratespost.ae)                                       |
| Emirates Sky Cargo                                | AE                                         | Asia     | `emirates_sky_cargo`                                | [https://www.skycargo.com](https://www.skycargo.com)                                             |
| EMPS Express                                      | CN                                         | Asia     | `emps_express`                                      | [https://www.empsexpress.com](https://www.empsexpress.com)                                       |
| Energia                                           | RU                                         | Europe   | `energia`                                           | [https://nrg-tk.ru](https://nrg-tk.ru)                                                           |
| Ensenda                                           | US                                         | Americas | `ensenda`                                           | [https://www.tforcelogistics.com](https://www.tforcelogistics.com)                               |
| Post Laos                                         | LA                                         | Asia     | `post_laos`                                         | [https://www.laopost.com.la](https://www.laopost.com.la)                                         |
| Entrego PH                                        | PH                                         | Asia     | `entrego_ph`                                        | [https://www.entrego.com.ph](https://www.entrego.com.ph)                                         |
| eParcel Korea                                     | KR                                         | Asia     | `eparcel_korea`                                     | [https://www.eparcel.kr](https://www.eparcel.kr)                                                 |
| EPS Express                                       | CN                                         | Asia     | `eps_express`                                       | [https://www.epsglobe.com](https://www.epsglobe.com)                                             |
| Equick China                                      | CN                                         | Asia     | `equick_china`                                      | [https://www.equick.cn](https://www.equick.cn)                                                   |
| Eritrea Post                                      | ER                                         | Africa   | `eritrea_post`                                      | [https://www.etsstar.com](https://www.etsstar.com)                                               |
| Eshipping                                         | CN                                         | Asia     | `eshipping`                                         | [https://www.eshippinggateway.com](https://www.eshippinggateway.com)                             |
| EspeedPost                                        | CN                                         | Asia     | `espeedpost`                                        | [https://www.espeedpost.com](https://www.espeedpost.com)                                         |
| Estafeta                                          | MX                                         | Americas | `estafeta`                                          | [www.estafeta.com](http://www.estafeta.com)                                                      |
| Estes                                             | US,CA                                      | Americas | `estes`                                             | [https://www.estes-express.com](https://www.estes-express.com)                                   |
| Ethiopian Post                                    | ET                                         | Africa   | `ethiopian_post`                                    | [https://ethio.post](https://ethio.post)                                                         |
| Etrak                                             | GB                                         | Europe   | `etrak`                                             | [https://track.etrak.io](https://track.etrak.io)                                                 |
| Evri 2.0                                          | GB                                         | Europe   | `hermes_uk`                                         | [https://www.evri.com](https://www.evri.com)                                                     |
| EWE Global Express                                | AU                                         | Oceania  | `ewe_global_express`                                | [https://www.ewe.com.au](https://www.ewe.com.au)                                                 |
| Exapaq                                            | FR                                         | Europe   | `exapaq`                                            | [https://www.exapaq.com](https://www.exapaq.com)                                                 |
| Exelot                                            | IL                                         | Asia     | `exelot`                                            | [https://public.exelot.com](https://public.exelot.com)                                           |
| Expeditors                                        | US                                         | Americas | `expeditors`                                        | [https://www.expeditors.com](https://www.expeditors.com)                                         |
| Express One                                       | HU                                         | Europe   | `express_one`                                       | [https://tracking.expressone.hu](https://tracking.expressone.hu)                                 |
| Ez Express                                        | CN                                         | Asia     | `ez_express`                                        | [https://www.owdiex.com](https://www.owdiex.com)                                                 |
| EZSHIP                                            | KR                                         | Asia     | `ezship`                                            | [https://ezshipkorea.co.kr](https://ezshipkorea.co.kr)                                           |
| FAN Courier                                       | RO                                         | Europe   | `fan_courier`                                       | [https://www.fancourier.ro](https://www.fancourier.ro)                                           |
| Fang Yuan Wu Liu                                  | CN                                         | Asia     | `fang_yuan_wu_liu`                                  | [https://www.hnfywl.com](https://www.hnfywl.com)                                                 |
| FAR International                                 | CN                                         | Asia     | `far_international`                                 | [https://m.far800.com](https://m.far800.com)                                                     |
| Faroe Post                                        | DK                                         | Europe   | `faroe_post`                                        | [www.posta.fo](http://www.posta.fo)                                                              |
| Fast and Furious                                  | ZA                                         | Africa   | `fast_and_furious`                                  | [https://www.fnf.co.za/index.html](https://www.fnf.co.za/index.html)                             |
| Fast Despatch Logistics                           | GB                                         | Europe   | `fast_despatch_logistics`                           | [https://fastdespatch.com](https://fastdespatch.com)                                             |
| Fast Express                                      | AU,TW                                      | Oceania  | `fast_express`                                      | [https://fastexpress.com.au](https://fastexpress.com.au)                                         |
| Fast Horse AU                                     | AU                                         | Oceania  | `fast_horse_au`                                     | [https://au.fh.express](https://au.fh.express)                                                   |
| Fastgo                                            | AU                                         | Oceania  | `fastgo`                                            | [https://www.fastgo.com.au](https://www.fastgo.com.au)                                           |
| Fastrak Services                                  | TH                                         | Asia     | `fastrak_services`                                  | [https://www.fastrak.co.th](https://www.fastrak.co.th)                                           |
| Fastway Ireland                                   | IE                                         | Europe   | `fastway_ireland`                                   | [https://www.fastway.ie](https://www.fastway.ie)                                                 |
| Fastway South Africa                              | ZA                                         | Africa   | `fastway_south_africa`                              | [https://www.fastway.co.za](https://www.fastway.co.za)                                           |
| FDS Express                                       | US                                         | Americas | `fds_express`                                       | [https://www.fdsexpress.com](https://www.fdsexpress.com)                                         |
| FedEx                                             | CA,US,MX,BR,CL,DM,BM,A                     | Global   | `fedex`                                             | [http://www.fedex.com](http://www.fedex.com)                                                     |
| Fedex China                                       | CN                                         | Asia     | `fedex_china`                                       | [https://cndxp.apac.fedex.com](https://cndxp.apac.fedex.com)                                     |
| FedEx France                                      | FR                                         | Europe   | `fedex_france`                                      | [https://france.fedex.com](https://france.fedex.com)                                             |
| FedEx Poland Domestic                             | PL                                         | Europe   | `fedex_poland_domestic`                             | [https://www.fedex.com](https://www.fedex.com)                                                   |
| FedEx UK                                          | GB                                         | Europe   | `fedex_uk`                                          | [https://www.fedex.com](https://www.fedex.com)                                                   |
| FENIX Express                                     | AE                                         | Asia     | `fenix_express`                                     | [https://express.fenix.life](https://express.fenix.life)                                         |
| FERCAM Logistics and Transport                    | IT                                         | Europe   | `fercam`                                            | [www.fercam.com](http://www.fercam.com)                                                          |
| Fetchr                                            | AE                                         | Asia     | `fetchr`                                            | [https://track.fetchr.us](https://track.fetchr.us)                                               |
| Fiji Post                                         | FJ                                         | Oceania  | `fiji_post`                                         | [www.postfiji.com.fj](http://www.postfiji.com.fj)                                                |
| First Flight Couriers                             | IN                                         | Asia     | `first_flight_couriers`                             | [https://www.firstflight.com.sg](https://www.firstflight.com.sg)                                 |
| First Global Logistics                            | NZ                                         | Oceania  | `first_global_logistics`                            | [https://track.fgmailconnect.co.nz](https://track.fgmailconnect.co.nz)                           |
| First Line                                        | CN                                         | Asia     | `first_line`                                        | [https://www.firstline56.com](https://www.firstline56.com)                                       |
| First Logistics                                   | ID                                         | Asia     | `first_logistics`                                   | [https://www.firstlogistics.co.id](https://www.firstlogistics.co.id)                             |
| First Mile                                        | US                                         | Americas | `first_mile`                                        | [https://track.firstmile.com](https://track.firstmile.com)                                       |
| Flash Express Thailand                            | TH                                         | Asia     | `flash_express_thailand`                            | [https://www.flashexpress.co.th](https://www.flashexpress.co.th)                                 |
| Fleet Optics                                      | CA                                         | Americas | `fleet_optics`                                      | [https://fleetopticsinc.ca](https://fleetopticsinc.ca)                                           |
| Flow Commerce                                     | US                                         | Americas | `flow_commerce`                                     | [https://track.flow.io](https://track.flow.io)                                                   |
| Flyt Express                                      | CN                                         | Asia     | `flyt_express`                                      | [https://www.flytexpress.com](https://www.flytexpress.com)                                       |
| FMX                                               | MY                                         | Asia     | `fmx`                                               | [https://www.freightmark.com.my](https://www.freightmark.com.my)                                 |
| Forrun                                            | PK                                         | Asia     | `forrun`                                            | [https://forrun.co](https://forrun.co)                                                           |
| Forward Air                                       | US                                         | Americas | `forward_air`                                       | [https://www.forwardair.com](https://www.forwardair.com)                                         |
| Freightquote                                      | US                                         | Americas | `freightquote`                                      | [https://www.freightquote.com](https://www.freightquote.com)                                     |
| Fujie Express                                     | CN                                         | Asia     | `fujie_express`                                     | [https://www.fujexp.com](https://www.fujexp.com)                                                 |
| Fulfilla                                          | US                                         | Americas | `fulfilla`                                          | [https://fulfilla.net](https://fulfilla.net)                                                     |
| Fulfillant                                        | CN                                         | Asia     | `fulfillant`                                        | [https://track-sp.com](https://track-sp.com)                                                     |
| Fulfillmen                                        | CN                                         | Asia     | `fulfillmen`                                        | [https://track.fulfillmen.com](https://track.fulfillmen.com)                                     |
| Gambia Post                                       | GM                                         | Africa   | `gambia_post`                                       | [www.gampost.gm](http://www.gampost.gm)                                                          |
| Gati KWE                                          | IN                                         | Asia     | `gati_kwe`                                          | [www.gatikwe.com](http://www.gatikwe.com)                                                        |
| GBS Broker                                        | RU                                         | Europe   | `gbs_broker`                                        | [https://gbs-broker.ru](https://gbs-broker.ru)                                                   |
| GDEX                                              | MY                                         | Asia     | `gdex`                                              | [https://www.gdexpress.com](https://www.gdexpress.com)                                           |
| GDSK                                              | DE                                         | Europe   | `gdsk`                                              | [www.gdsk.de](http://www.gdsk.de)                                                                |
| Geis CZ                                           | CZ                                         | Europe   | `geis_cz`                                           | [https://www.geis-group.cz](https://www.geis-group.cz)                                           |
| Geis Germany                                      | DE                                         | Europe   | `geis_germany`                                      | [https://tt.geis-group.de](https://tt.geis-group.de)                                             |
| Geniki Taxydromiki                                | GR                                         | Europe   | `geniki_taxydromiki`                                | [https://www.taxydromiki.gr](https://www.taxydromiki.gr)                                         |
| Geodis E-space                                    | FR                                         | Europe   | `geodis_espace`                                     | [https://www.geodis.com/](https://www.geodis.com/)                                               |
| Georgian Post                                     | GE                                         | Asia     | `georgian_post`                                     | [www.gpost.ge](http://www.gpost.ge)                                                              |
| GESWL Express                                     | CN                                         | Asia     | `geswl_express`                                     | [https://www.geswl.com](https://www.geswl.com)                                                   |
| GFS Delivery                                      | GB                                         | Europe   | `gfs_delivery`                                      | [https://tracking.justshoutgfs.com](https://tracking.justshoutgfs.com)                           |
| Ghana Post                                        | GH                                         | Africa   | `ghana_post`                                        | [https://www.ghanapost.com.gh](https://www.ghanapost.com.gh)                                     |
| Giao Hàng Nhanh                                  | VN                                         | Asia     | `giao_hang_nhanh`                                   | [www.giaohangnhanh.vn](http://www.giaohangnhanh.vn)                                              |
| Gibraltar Post                                    | GI                                         | Europe   | `gibraltar_post`                                    | [https://post.gi](https://post.gi)                                                               |
| GIO Express                                       | US                                         | Americas | `gio_express`                                       | [https://gio.e-courier.com](https://gio.e-courier.com)                                           |
| Global Post                                       | US                                         | Americas | `global_post`                                       | [https://www.goglobalpost.com](https://www.goglobalpost.com)                                     |
| GLS Canada                                        | CA                                         | Americas | `gls_canada`                                        | [https://www.gls-canada.com](https://www.gls-canada.com)                                         |
| GLS Croatia                                       | HR                                         | Europe   | `gls_croatia`                                       | [https://online.gls-croatia.com](https://online.gls-croatia.com)                                 |
| GLS Hungary                                       | HU                                         | Europe   | `gls_hungary`                                       | [https://online.gls-hungary.com](https://online.gls-hungary.com)                                 |
| GLS Italy                                         | IT                                         | Europe   | `gls_italy`                                         | [https://www.gls-italy.com](https://www.gls-italy.com)                                           |
| GLS Portugal                                      | PT                                         | Europe   | `gls_portugal`                                      | [https://m.gls-portugal.com](https://m.gls-portugal.com)                                         |
| GLS Slovakia                                      | SK                                         | Europe   | `gls_slovakia`                                      | [https://online.gls-slovakia.sk](https://online.gls-slovakia.sk)                                 |
| GLS Slovenia                                      | SI                                         | Europe   | `gls_slovenia`                                      | [https://online.gls-slovenia.com](https://online.gls-slovenia.com)                               |
| Go Express                                        | ID                                         | Asia     | `go_express`                                        | [https://icms-d2d.garuda-indonesia.com](https://icms-d2d.garuda-indonesia.com)                   |
| Go Express New Zealand                            | NZ                                         | Oceania  | `go_express_new_zealand`                            | [https://www.goex.co.nz](https://www.goex.co.nz)                                                 |
| Go Go Xpress                                      | PH                                         | Asia     | `go_go_xpress`                                      | [https://app.gogoxpress.com](https://app.gogoxpress.com)                                         |
| Go Rush                                           | BN                                         | Asia     | `go_rush`                                           | [https://www.gorushbn.com](https://www.gorushbn.com)                                             |
| GO Express and Logistics                          | DE                                         | Europe   | `go_express_and_logistics`                          | [https://www.general-overnight.com/](https://www.general-overnight.com/)                         |
| Godtrans                                          | PE                                         | Americas | `godtrans`                                          | [https://sistemas.ggvb.com.pe](https://sistemas.ggvb.com.pe)                                     |
| GoFly                                             | CN                                         | Asia     | `gofly`                                             | [https://goflyi.com](https://goflyi.com)                                                         |
| GoJavas                                           | IN                                         | Asia     | `gojavas`                                           | [https://gojavas.com](https://gojavas.com)                                                       |
| Grenada Post                                      | GD                                         | Americas | `grenada_post`                                      | [www.grenadapostal.com](http://www.grenadapostal.com)                                            |
| Greyhound                                         | CA                                         | Americas | `greyhound`                                         | [https://www.shipgreyhound.com](https://www.shipgreyhound.com)                                   |
| Grupo ampm                                        | MX                                         | Americas | `grupo_ampm`                                        | [https://www.grupoampm.com](https://www.grupoampm.com)                                           |
| GSI EXPRESS                                       | KR                                         | Asia     | `gsi_express`                                       | [https://gsiexpress.com](https://gsiexpress.com)                                                 |
| GTA GSM                                           | US                                         | Americas | `gta_gsm`                                           | [https://gtagsm.com](https://gtagsm.com)                                                         |
| Guangdong Weisuyi Information Technology (WSE)    | CN                                         | Asia     | `gdwse`                                             | [https://www.gdwse.com/](https://www.gdwse.com/)                                                 |
| Guernsey Post                                     | GB                                         | Europe   | `guernsey_post`                                     | [www.guernseypost.com](http://www.guernseypost.com)                                              |
| Guinea Post                                       | GN                                         | Africa   | `guinea_post`                                       | [https://www.postpng.com.pg](https://www.postpng.com.pg)                                         |
| Guyana Post                                       | GY                                         | Americas | `guyana_post`                                       | [https://guypost.gy](https://guypost.gy)                                                         |
| Haiti Post                                        | HT                                         | Americas | `haiti_post`                                        | postehaiti.gouv.ht                                                                               |
| Hanjin                                            | KR                                         | Asia     | `hanjin`                                            | [https://www.hanjin.co.kr](https://www.hanjin.co.kr)                                             |
| Happy Post                                        | FR                                         | Europe   | `happy_post`                                        | [https://happy-post.com](https://happy-post.com)                                                 |
| Hartmann International                            | DE                                         | Europe   | `hartmann_international`                            | [https://cp.hartmann-international.de](https://cp.hartmann-international.de)                     |
| Haypost                                           | AM                                         | Asia     | `haypost`                                           | [https://www.haypost.am](https://www.haypost.am)                                                 |
| HCT Logistics                                     | TW                                         | Asia     | `hct_logistics`                                     | [https://www.hct.com.tw](https://www.hct.com.tw)                                                 |
| Hellmann Worldwide Logistics                      | US                                         | Americas | `hellmann_worldwide_logistics`                      | [https://portal.emea.hellmann.net](https://portal.emea.hellmann.net)                             |
| Helthjem                                          | NO                                         | Europe   | `helthjem`                                          | [https://helthjem.no](https://helthjem.no)                                                       |
| Heppner Internationale Spedition Group            | DE                                         | Europe   | `hepner_group`                                      | [https://www.heppner-group.com/de/](https://www.heppner-group.com/de/)                           |
| Hermes 2 Man Handling                             | DE                                         | Europe   | `hermes_two_man_handling`                           | [https://myhes.de/](https://myhes.de/)                                                           |
| Hermes Europe                                     | RU,DE,FR,IT,ES,UA,PL,RO                    | Europe   | `hermes_europe`                                     | [https://www.hermes-europe.co.uk](https://www.hermes-europe.co.uk)                               |
| Hermes Germany                                    | DE                                         | Europe   | `hermes_germany_b2c`                                | [https://www.myhermes.de](https://www.myhermes.de)                                               |
| Hermes Italy                                      | IT                                         | Europe   | `hermes_italy`                                      | [www.hermes-italy.it](http://www.hermes-italy.it)                                                |
| Hermesworld                                       | GB                                         | Europe   | `hermesworld`                                       | [https://hermesworld.com](https://hermesworld.com)                                               |
| Hero Express                                      | AU                                         | Oceania  | `hero_express`                                      | [https://www.heroexpress.com.au](https://www.heroexpress.com.au)                                 |
| heyworld                                          | DE                                         | Europe   | `heyworld`                                          | [https://api.tms.heyworld.com](https://api.tms.heyworld.com)                                     |
| HHEXP                                             | CN                                         | Asia     | `hhexp`                                             | [https://www.hh-exp.com](https://www.hh-exp.com)                                                 |
| Holisol                                           | IN                                         | Asia     | `holisol`                                           | [https://holisollogistics.com](https://holisollogistics.com)                                     |
| Homerr                                            | NL                                         | Europe   | `homerr`                                            | [https://track.homerr.com](https://track.homerr.com)                                             |
| Hong Hai Supply Chain                             | CN                                         | Asia     | `hong_hai_supply_chain`                             | [https://www.gzbtygj.com](https://www.gzbtygj.com)                                               |
| Honold                                            | DE                                         | Europe   | `honold`                                            | [https://tt.honold.net](https://tt.honold.net)                                                   |
| HR Parcel                                         | IT                                         | Europe   | `hr_parcel`                                         | [https://tracking.myhrparcel.com](https://tracking.myhrparcel.com)                               |
| Hrvatska Pošta / Croatian Post                   | HR                                         | Europe   | `croatian_post`                                     | [www.posta.hr](http://www.posta.hr)                                                              |
| Hua Han Logistics                                 | CN                                         | Asia     | `hua_han_logistics`                                 | [https://www.hh-exp.com](https://www.hh-exp.com)                                                 |
| Huahai Express                                    |                                            |          | `huahai_express`                                    | [https://www.huahaiexpress.com](https://www.huahaiexpress.com)                                   |
| HUBBED                                            | AU                                         | Oceania  | `hubbed`                                            | [https://hubbed.com](https://hubbed.com)                                                         |
| Hunter Express                                    | AU                                         | Oceania  | `hunter_express`                                    | [www.hunterexpress.com.au](http://www.hunterexpress.com.au)                                      |
| i-parcel                                          | US                                         | Americas | `i_parcel`                                          | [www.i-parcel.com](http://www.i-parcel.com)                                                      |
| Iceland Post                                      | IS                                         | Europe   | `iceland_post`                                      | [https://posturinn.is](https://posturinn.is)                                                     |
| iCumulus                                          | AU                                         | Oceania  | `icumulus`                                          | [https://tracking.icumulus.cloud](https://tracking.icumulus.cloud)                               |
| iDexpress                                         | ID                                         | Asia     | `idexpress`                                         | [https://idexpress.com](https://idexpress.com)                                                   |
| ILOXX                                             | DE                                         | Europe   | `iloxx`                                             | [www.iloxx.de](http://www.iloxx.de)                                                              |
| ILYANG Express                                    | KR                                         | Asia     | `ilyang_express`                                    | [https://www.ilyanglogis.com](https://www.ilyanglogis.com)                                       |
| IMEX Global Solutions                             | US,CA,ES,PH,HT                             | Americas | `imex_global_solutions`                             | [www.imexglobalsolutions.com](http://www.imexglobalsolutions.com)                                |
| iMile Delivery                                    | AE,SA,MX,CN,MA,OM,KW                       | Asia     | `imile_delivery`                                    | [https://www.imile.com](https://www.imile.com)                                                   |
| IML Express                                       | RU                                         | Europe   | `iml_express`                                       | [https://iml.ru](https://iml.ru)                                                                 |
| IMX Mail                                          | GB,FR,ES,BE,CZ,IT                          | Europe   | `imx_mail`                                          | [https://suivi.imxpostal.fr](https://suivi.imxpostal.fr)                                         |
| India Post                                        | IN                                         | Asia     | `india_post`                                        | [www.indiapost.gov.in](http://www.indiapost.gov.in)                                              |
| Inex Post                                         | RU                                         | Europe   | `inex_post`                                         | [https://www.inexpost.ru](https://www.inexpost.ru)                                               |
| Inposdom                                          | DO                                         | Americas | `inposdom`                                          | [https://globaltracktrace.ptc.post](https://globaltracktrace.ptc.post)                           |
| InPost Paczkomaty                                 | PL                                         | Europe   | `inpost_paczkomaty`                                 | [https://inpost.pl](https://inpost.pl)                                                           |
| InPost UK                                         | GB                                         | Europe   | `inpost_uk`                                         | [https://inpost.co.uk](https://inpost.co.uk)                                                     |
| Instant                                           | MY                                         | Asia     | `instant`                                           | [https://tnedsss.tiongnam.com](https://tnedsss.tiongnam.com)                                     |
| Intelcom Express                                  | CA                                         | Americas | `intelcom_express`                                  | [https://intelcom.ca](https://intelcom.ca)                                                       |
| Inter Rapidisimo                                  | CO                                         | Americas | `inter_rapidisimo`                                  | [https://interrapidisimo.com](https://interrapidisimo.com)                                       |
| InterEx                                           | HR                                         | Europe   | `interex`                                           | [https://www.interex.hr](https://www.interex.hr)                                                 |
| International Seur                                | ES,PT                                      | Europe   | `international_seur`                                | [https://www.seur.com](https://www.seur.com)                                                     |
| Internet Express                                  | ZA                                         | Africa   | `internet_express`                                  | [https://www.internetexpress.co.za](https://www.internetexpress.co.za)                           |
| InterParcel                                       | GB                                         | Europe   | `interparcel`                                       | [https://uk.interparcel.com](https://uk.interparcel.com)                                         |
| Interparcel Australia                             | AU                                         | Oceania  | `interparcel_australia`                             | [https://au.interparcel.com](https://au.interparcel.com)                                         |
| Ipostel                                           | VE                                         | Americas | `ipostel`                                           | [www.ipostel.gob.ve](http://www.ipostel.gob.ve)                                                  |
| Iran Post                                         | IR                                         | Asia     | `iran_post`                                         | [www.post.ir](http://www.post.ir)                                                                |
| Iraqi Post                                        | IQ                                         | Asia     | `iraqi_post`                                        | [www.iraqipost.net](http://www.iraqipost.net)                                                    |
| Israel Post                                       | IL                                         | Asia     | `israel_post`                                       | [https://www.israelpost.co.il](https://www.israelpost.co.il)                                     |
| Italy SDA                                         | IT                                         | Europe   | `italy_sda`                                         | [https://www.sda.it](https://www.sda.it)                                                         |
| Ivoy                                              | MX                                         | Americas | `ivoy`                                              | [https://tracking.ivoy.mx](https://tracking.ivoy.mx)                                             |
| J Express                                         | ID                                         | Asia     | `j_express`                                         | [https://www.j-express.id](https://www.j-express.id)                                             |
| J NET                                             | CN                                         | Asia     | `j_net`                                             | [https://www.j-net.cn](https://www.j-net.cn)                                                     |
| J\&T CARGO                                        | ID                                         | Asia     | `jt_cargo`                                          | [https://www.jtcargo.id/](https://www.jtcargo.id/)                                               |
| J\&T Express                                      | ID                                         | Asia     | `jt_express`                                        | [https://www.jet.co.id/](https://www.jet.co.id/)                                                 |
| J\&T Express Philippines                          | PH                                         | Asia     | `jt_express_philippines`                            | [https://www.jtexpress.ph/](https://www.jtexpress.ph/)                                           |
| J\&T Express Saudi Arabia (KSA)                   | SA                                         | Asia     | `jt_express_saudi_arabia`                           | [https://www.jtexpress-sa.com/](https://www.jtexpress-sa.com/)                                   |
| J\&T Express SG                                   | SG                                         | Asia     | `jt_express_sg`                                     | [https://www.jtexpress.sg/](https://www.jtexpress.sg/)                                           |
| J\&T Indonesia                                    | ID                                         | Asia     | `jt_indonesia`                                      | [www.jet.co.id](http://www.jet.co.id)                                                            |
| J\&T International Logistics                      | CN                                         | Asia     | `jt_international_logistics`                        | [https://www.jet-logistics.com/en/](https://www.jet-logistics.com/en/)                           |
| J\&T Malaysia                                     | MY                                         | Asia     | `jt_malaysia`                                       | [https://jtexpress.my/index.php](https://jtexpress.my/index.php)                                 |
| Jam Express                                       | PH                                         | Asia     | `jam_express`                                       | [https://www.myjamexpress.com](https://www.myjamexpress.com)                                     |
| Jamaica Post                                      | JM                                         | Americas | `jamaica_post`                                      | [www.jamaicapost.gov.jm](http://www.jamaicapost.gov.jm)                                          |
| Janco Ecommerce                                   | HK                                         | Asia     | `janco_ecommerce`                                   | [https://www.jancoecommerce.com](https://www.jancoecommerce.com)                                 |
| Janio                                             | SG                                         | Asia     | `janio`                                             | [https://tracker.janio.asia](https://tracker.janio.asia)                                         |
| Japan Post                                        | JP                                         | Asia     | `japan_post`                                        | [https://trackings.post.japanpost.jp](https://trackings.post.japanpost.jp)                       |
| Jayon Express (JEX)                               | ID,SG                                      | Asia     | `jayon_express`                                     | [www.jayonexpress.com](http://www.jayonexpress.com)                                              |
| JCEX                                              | CN                                         | Asia     | `jcex`                                              | [https://www.jcex.com](https://www.jcex.com)                                                     |
| Jersey Post                                       | JE                                         | Europe   | `jersey_post`                                       | [https://www.jerseypost.com](https://www.jerseypost.com)                                         |
| Jet Cargo                                         | PE                                         | Americas | `jet_cargo`                                         | [https://jetcargoservice.com](https://jetcargoservice.com)                                       |
| Jet-Ship Worldwide                                | MY,SG,PH                                   | Asia     | `jet_ship_worldwide`                                | [www.jet-ship.com](http://www.jet-ship.com)                                                      |
| JNE                                               | ID                                         | Asia     | `jne`                                               | [https://www.jne.co.id](https://www.jne.co.id)                                                   |
| Jocom                                             | MY                                         | Asia     | `jocom`                                             | [https://www.jocom.my](https://www.jocom.my)                                                     |
| Joeyco                                            | CA                                         | Americas | `joeyco`                                            | [https://www.joeyco.com](https://www.joeyco.com)                                                 |
| Joom Logistics                                    | CN                                         | Asia     | `joom_logistics`                                    | [https://joomlogistics.com](https://joomlogistics.com)                                           |
| Jordan Post                                       | JO                                         | Asia     | `jordan_post`                                       | [https://jordanpost.com.jo](https://jordanpost.com.jo)                                           |
| JP BH Pošta                                      | BA                                         | Europe   | `jp_bh_posta`                                       | [www.posta.ba](http://www.posta.ba)                                                              |
| JS Express                                        | CN                                         | Asia     | `js_express`                                        | [https://www.js-exp.com](https://www.js-exp.com)                                                 |
| Kangaroo Worldwide Express                        | MY                                         | Asia     | `kangaroo_worldwide_express`                        | [https://www.kangaroo.com.my](https://www.kangaroo.com.my)                                       |
| KARGO                                             | PT                                         | Europe   | `kargo`                                             | [https://www.kargo.pt](https://www.kargo.pt)                                                     |
| Kart2Door/SmartKargo                              | US                                         | Americas | `kart_to_door`                                      | [https://www.kart2door.com/](https://www.kart2door.com/)                                         |
| Kaz Post                                          | KZ                                         | Asia     | `kaz_post`                                          | [www.kazpost.kz](http://www.kazpost.kz)                                                          |
| Keen And Able                                     | GB                                         | Europe   | `keen_and_able`                                     | [https://www.keenandabledelivery.com](https://www.keenandabledelivery.com)                       |
| Kenya Post                                        | KE                                         | Africa   | `kenya_post`                                        | [www.posta.co.ke](http://www.posta.co.ke)                                                        |
| Kerry Ecommerce                                   | CN                                         | Asia     | `kerry_ecommerce`                                   | [https://kerry-ecommerce.com](https://kerry-ecommerce.com)                                       |
| Kerry Express Hong Kong                           | HK                                         | Asia     | `kerry_express_hong_kong`                           | [https://hk.kerryexpress.com](https://hk.kerryexpress.com)                                       |
| Kerry Express Thailand                            | TH                                         | Asia     | `kerry_express_thailand`                            | [https://th.kerryexpress.com](https://th.kerryexpress.com)                                       |
| Kerry Logistics                                   | HK                                         | Asia     | `kerry_logistics`                                   | [https://www.kerrylogistics.com](https://www.kerrylogistics.com)                                 |
| Kerry TJ Logistics                                | CN                                         | Asia     | `kerry_tj_logistics`                                | [https://www.kerrytj.com](https://www.kerrytj.com)                                               |
| Kerry TTC Express                                 | VN                                         | Asia     | `kerry_ttc_express`                                 | [https://kerryexpress.com.vn](https://kerryexpress.com.vn)                                       |
| KEX Express                                       | MY                                         | Asia     | `kex_express`                                       | [https://www.abxexpress.com.my](https://www.abxexpress.com.my)                                   |
| KGM Hub                                           | SG                                         | Asia     | `kgm_hub`                                           | [https://www.kgmhub.com](https://www.kgmhub.com)                                                 |
| Kiala Netherlands                                 | NL                                         | Europe   | `kiala_netherlands`                                 | [https://www.ups.com](https://www.ups.com)                                                       |
| Kintetsu World Express                            | JP                                         | Asia     | `kintetsu_world_express`                            | [https://css.kwe.com](https://css.kwe.com)                                                       |
| Koester Hapke Spedition                           | DE                                         | Europe   | `koester_hapke_spedition`                           | [https://tracking.koester-hapke-sped.com](https://tracking.koester-hapke-sped.com)               |
| Komon Express                                     |                                            |          | `komon_express`                                     | [https://komonexpress.cn](https://komonexpress.cn)                                               |
| Korea Post                                        | KR                                         | Asia     | `korea_post`                                        | [https://www.koreapost.go.kr](https://www.koreapost.go.kr)                                       |
| Kosovo Post                                       | RS                                         | Europe   | `kosovo_post`                                       | [https://www.postakosoves.com](https://www.postakosoves.com)                                     |
| Kronos Express                                    | GR                                         | Europe   | `kronos_express`                                    | [https://www.kronosexpress.com](https://www.kronosexpress.com)                                   |
| Kuehne + Nagel                                    | CH                                         | Europe   | `kuehne_nagel`                                      | [www.kn-portal.com](http://www.kn-portal.com)                                                    |
| Kurasi                                            | ID                                         | Asia     | `kurasi`                                            | [https://www.kurasi.co.id](https://www.kurasi.co.id)                                             |
| Kuwait Post                                       | KW                                         | Asia     | `kuwait_post`                                       | [https://www.tracking.moc.gov.kw](https://www.tracking.moc.gov.kw)                               |
| KWT                                               | CN                                         | Asia     | `kwt`                                               | [https://www.kwt56.com](https://www.kwt56.com)                                                   |
| Kyrgyz Express Post                               | KG                                         | Asia     | `kyrgyz_express_post`                               | [https://www.kep.kg](https://www.kep.kg)                                                         |
| Kyrgyz Post                                       | KG                                         | Asia     | `kyrgyz_post`                                       | kyrgyzpost.kg                                                                                    |
| Kyungdong Parcel                                  | KR                                         | Asia     | `kyungdong_parcel`                                  | [https://kdexp.com](https://kdexp.com)                                                           |
| La Poste                                          | FR                                         | Europe   | `la_poste`                                          | [www.csuivi.courrier.laposte.fr](http://www.csuivi.courrier.laposte.fr)                          |
| La Poste Burkina Faso                             | BF                                         | Africa   | `la_poste_burkina_faso`                             | [https://webtracking.laposte.bf](https://webtracking.laposte.bf)                                 |
| La Poste De Benin                                 | BJ                                         | Africa   | `la_poste_de_benin`                                 | [www.laposte.bj](http://www.laposte.bj)                                                          |
| La Poste De Côte d'Ivoire                        | CI                                         | Africa   | `la_poste_ivory_coast`                              | [www.laposte.ci](http://www.laposte.ci)                                                          |
| La Poste De Djibouti                              | DJ                                         | Africa   | `la_poste_de_djibouti`                              | [www.laposte.dj](http://www.laposte.dj)                                                          |
| La Poste De Mali                                  | ML                                         | Africa   | `la_poste_de_mali`                                  | [www.laposte.ml](http://www.laposte.ml)                                                          |
| La Poste De Monaco                                | MC                                         | Europe   | `la_poste_de_monaco`                                | [www.lapostemonaco.mc](http://www.lapostemonaco.mc)                                              |
| La Poste De Senegal                               | SN                                         | Africa   | `la_poste_de_senegal`                               | [www.laposte.sn](http://www.laposte.sn)                                                          |
| La Poste De Togo                                  | TG                                         | Africa   | `la_poste_de_togo`                                  | [www.laposte.tg](http://www.laposte.tg)                                                          |
| La Poste De Tunisia                               | TN                                         | Africa   | `la_poste_de_tunisia`                               | [www.poste.tn](http://www.poste.tn)                                                              |
| Landair                                           | US                                         | Americas | `landair`                                           | [https://www.mylandair.com](https://www.mylandair.com)                                           |
| Landmark Global                                   | NL                                         | Europe   | `landmark_global`                                   | [https://track.landmarkglobal.com](https://track.landmarkglobal.com)                             |
| Latvia Post                                       | LV                                         | Europe   | `latvia_post`                                       | [www.pasts.lv](http://www.pasts.lv)                                                              |
| LBC Express                                       | PH                                         | Asia     | `lbc_express`                                       | [https://www.lbcexpress.com](https://www.lbcexpress.com)                                         |
| Legion Express                                    | SG                                         | Asia     | `legion_express`                                    | [https://legionexp.com](https://legionexp.com)                                                   |
| Leman                                             | SE                                         | Europe   | `leman`                                             | [https://track.yourleman.com](https://track.yourleman.com)                                       |
| Lesotho Post                                      | LS                                         | Africa   | `lesotho_post`                                      | lesothopost.org.ls                                                                               |
| LexShip                                           | IN                                         | Asia     | `lexship`                                           | [https://track.lexship.com](https://track.lexship.com)                                           |
| Liban Post                                        | LB                                         | Asia     | `liban_post`                                        | [www.libanpost.com](http://www.libanpost.com)                                                    |
| Liberia Post                                      | LR                                         | Africa   | `liberia_post`                                      | [www.mopt.gov.lr](http://www.mopt.gov.lr)                                                        |
| Libya Post                                        | LY                                         | Africa   | `libya_post`                                        | [https://tracking.libyapost.ly](https://tracking.libyapost.ly)                                   |
| LICCARDI EXPRESS COURIER                          | IT                                         | Europe   | `liccardi_express_courier`                          | [https://my.liccarditrasporti.com](https://my.liccarditrasporti.com)                             |
| Liechtenstein Post                                | LI                                         | Europe   | `liechtenstein_post`                                | [www.post.li](http://www.post.li)                                                                |
| Lietuvos Paštas/ Lithuania Post                  | LT                                         | Europe   | `lithuania_post`                                    | [www.post.lt](http://www.post.lt)                                                                |
| Line Clear                                        | MY                                         | Asia     | `line_clear`                                        | [https://www.lineclearexpress.com](https://www.lineclearexpress.com)                             |
| Line Clear Express & Logistics                    | MY                                         | Asia     | `line_clear_express_logistics`                      | [https://www.lineclearexpress.com/](https://www.lineclearexpress.com/)                           |
| Lion Parcel                                       | ID                                         | Asia     | `lion_parcel`                                       | [https://lionparcel.com](https://lionparcel.com)                                                 |
| Logen                                             | KR                                         | Asia     | `logen`                                             | [https://www.ilogen.com](https://www.ilogen.com)                                                 |
| Loghistes                                         | IT                                         | Europe   | `loghistes`                                         | [https://web.loghistes.it](https://web.loghistes.it)                                             |
| Logisters                                         | CN                                         | Asia     | `logisters`                                         | [https://www.logisters.com](https://www.logisters.com)                                           |
| Logistic Worldwide Express                        | MY,CN,SG,KR,HK                             | Asia     | `logistic_worldwide_express`                        | [https://www.lwe.com.hk](https://www.lwe.com.hk)                                                 |
| Logistika                                         | MY                                         | Asia     | `logistika`                                         | [https://track.setel.com](https://track.setel.com)                                               |
| Logwin                                            | LU                                         | Europe   | `logwin`                                            | [https://www.logwin-logistics.com](https://www.logwin-logistics.com)                             |
| Lone Star Overnight                               | US                                         | Americas | `lso`                                               | [https://www.lso.com/](https://www.lso.com/)                                                     |
| Loomis Express                                    | FR                                         | Europe   | `loomis_express`                                    | [https://www.loomisexpress.com](https://www.loomisexpress.com)                                   |
| Lotte Global Logistics                            | KR                                         | Asia     | `lotte_global_logistics`                            | [https://www.lotteglogis.com](https://www.lotteglogis.com)                                       |
| LTIAN EXP                                         | CN                                         | Asia     | `ltian_exp`                                         | [https://www.ltianexp.com](https://www.ltianexp.com)                                             |
| LTL                                               | KP                                         | Asia     | `ltl`                                               | [https://ltl.kr](https://ltl.kr)                                                                 |
| Luxembourg Post                                   | LU                                         | Europe   | `luxembourg_post`                                   | [www.post.lu](http://www.post.lu)                                                                |
| Lyne Direct                                       | AU                                         | Oceania  | `lyne_direct`                                       | [https://lynedirect.com](https://lynedirect.com)                                                 |
| M Xpress                                          | MY                                         | Asia     | `m_xpress`                                          | [https://gold.mxpress2u.net](https://gold.mxpress2u.net)                                         |
| M-Dis                                             | IT                                         | Europe   | `m_dis`                                             | [https://www.primaedicola](https://www.primaedicola). it/puntodiritiro/search/view/              |
| M3 Logistics                                      | AU                                         | Oceania  | `m3_logistics`                                      | [https://ics.m3logistics.com](https://ics.m3logistics.com)                                       |
| Macau Post                                        | CN                                         | Asia     | `macau_post`                                        | [https://www.ctt.gov.mo](https://www.ctt.gov.mo)                                                 |
| Macedonia Post                                    | MK                                         | Europe   | `macedonia_post`                                    | [https://www.posta.com.mk](https://www.posta.com.mk)                                             |
| MACH 1 GLOBAL SERVICES INC                        | US                                         | Americas | `mach_1_global_services_inc`                        | [https://m1aent.webtracker.wisegrid.net](https://m1aent.webtracker.wisegrid.net)                 |
| Madroo Express                                    | CN                                         | Asia     | `madroo_express`                                    | [https://www.madrooex.com](https://www.madrooex.com)                                             |
| MAERSK                                            | DK                                         | Europe   | `maersk`                                            | [https://www.maersk.com](https://www.maersk.com)                                                 |
| Magyar Posta                                      | HU                                         | Europe   | `magyar_posta`                                      | [https://www.posta.hu](https://www.posta.hu)                                                     |
| MAIL BOXES ETC                                    | IT                                         | Europe   | `mail_boxes_etc`                                    | [https://www.mbe.it](https://www.mbe.it)                                                         |
| MailAmericas                                      | US,AR,CO,MX,GB,PL,HK,CN                    | Americas | `mailamericas`                                      | [www.mailamericas.com](http://www.mailamericas.com)                                              |
| Mainfreight                                       | NZ                                         | Oceania  | `mainfreight`                                       | [https://www.mainfreight.com](https://www.mainfreight.com)                                       |
| Major Express                                     | RU                                         | Europe   | `major_express`                                     | [https://major-express.ru](https://major-express.ru)                                             |
| Malawi Post                                       | MW                                         | Africa   | `malawi_post`                                       | [www.malawiposts.com](http://www.malawiposts.com)                                                |
| Malaysia Post / Poslaju                           | MY                                         | Asia     | `malaysia_post`                                     | [https://www.pos.com.my/](https://www.pos.com.my/)                                               |
| MalcaAmit                                         | CA                                         | Americas | `malca_amit`                                        | [https://www.malca-amit.com/](https://www.malca-amit.com/)                                       |
| Maldives Post                                     | MV                                         | Asia     | `maldives_post`                                     | [https://www.maldivespost.com](https://www.maldivespost.com)                                     |
| Malta Post                                        | MT                                         | Europe   | `malta_post`                                        | [www.maltapost.com](http://www.maltapost.com)                                                    |
| Mara Xpress                                       | AE                                         | Asia     | `mara_xpress`                                       | [https://www.maraxpress.com](https://www.maraxpress.com)                                         |
| Matdespatch                                       | MY                                         | Asia     | `matdespatch`                                       | [https://www.matdespatch.com](https://www.matdespatch.com)                                       |
| Matkahuolto                                       | FI                                         | Europe   | `matkahuolto`                                       | [https://www.matkahuolto.fi](https://www.matkahuolto.fi)                                         |
| Mauritanian Post                                  | MR                                         | Africa   | `mauritanian_post`                                  | [www.mauripost.mr](http://www.mauripost.mr)                                                      |
| Mauritius Post                                    | MU                                         | Africa   | `mauritius_post`                                    | [https://www.mauritiuspost.mu](https://www.mauritiuspost.mu)                                     |
| MBW Courier Inc                                   | US,CA                                      | Americas | `mbw_courier_inc`                                   | [https://portal.shiptrackapp.com](https://portal.shiptrackapp.com)                               |
| Meest                                             | GB                                         | Europe   | `meest`                                             | [https://international.meest.com](https://international.meest.com)                               |
| Mercury Business Services                         | US                                         | Americas | `mercury_business_services`                         | [https://www.shipmercury.com](https://www.shipmercury.com)                                       |
| Meteor Space                                      | GB                                         | Europe   | `meteor_space`                                      | [https://space.canary7.com](https://space.canary7.com)                                           |
| MEX Posta                                         | MK                                         | Europe   | `mex_posta`                                         | [https://mex.mk](https://mex.mk)                                                                 |
| Mexico AeroFlash                                  | MX                                         | Americas | `mexico_aeroflash`                                  | [https://www.aeroflash.com.mx](https://www.aeroflash.com.mx)                                     |
| Mexico Redpack                                    | MX                                         | Americas | `mexico_redpack`                                    | [https://www.redpack.com.mx](https://www.redpack.com.mx)                                         |
| Mexico Senda Express                              | MX                                         | Americas | `mexico_senda_express`                              | [https://www.sendaexpress.com.mx](https://www.sendaexpress.com.mx)                               |
| Mhi                                               | GB                                         | Europe   | `mhi`                                               | [https://www.trackmail.co.uk](https://www.trackmail.co.uk)                                       |
| Mikropakket                                       | NL                                         | Europe   | `mikropakket`                                       | [https://www.mikropakket.nl](https://www.mikropakket.nl)                                         |
| Minimax Express                                   | CA                                         | Americas | `minimax_express`                                   | [https://www.minimaxexpress.com](https://www.minimaxexpress.com)                                 |
| Mitsui O.S.K Lines                                | JP                                         | Asia     | `mitsui_osk_lines`                                  | [https://www.mol.co.jp/en/](https://www.mol.co.jp/en/)                                           |
| Miuson International                              | CN                                         | Asia     | `miuson_international`                              | [www.miuson.net](http://www.miuson.net)                                                          |
| Moldova Post                                      | MD                                         | Europe   | `moldova_post`                                      | [https://www.posta.md](https://www.posta.md)                                                     |
| Mondial Relay                                     | FR,BE                                      | Europe   | `mondial_relay`                                     | [www.mondialrelay.fr](http://www.mondialrelay.fr)                                                |
| Mongol Post                                       | MN                                         | Asia     | `mongol_post`                                       | [www.mongolpost.mn](http://www.mongolpost.mn)                                                    |
| Montenegro Post                                   | ME                                         | Europe   | `montenegro_post`                                   | [https://webpostar.postacg.me](https://webpostar.postacg.me)                                     |
| Moove Logistica                                   | PT                                         | Europe   | `moove_logistica`                                   | [https://tracking.moovelogistica.pt](https://tracking.moovelogistica.pt)                         |
| Moovin                                            | CR,HN                                      | Americas | `moovin`                                            | [https://moovin.me](https://moovin.me)                                                           |
| Morning Express                                   | HK                                         | Asia     | `morning_express`                                   | [www.mechk.com](http://www.mechk.com)                                                            |
| Morocco Post                                      | MA                                         | Africa   | `morocco_post`                                      | [www.poste.ma](http://www.poste.ma)                                                              |
| MRW                                               | ES                                         | Europe   | `mrw`                                               | [https://www.mrw.es](https://www.mrw.es)                                                         |
| MUDITA                                            | IN                                         | Asia     | `mudita`                                            | [https://www.muditacargo.com](https://www.muditacargo.com)                                       |
| MX Express                                        | CN                                         | Asia     | `mx_express`                                        | [https://www.mxe56.com](https://www.mxe56.com)                                                   |
| Myanma Post                                       | MM                                         | Asia     | `myanma_post`                                       | [www.myanmaposts.net.mm](http://www.myanmaposts.net.mm)                                          |
| Mypostonline                                      | MY                                         | Asia     | `mypostonline`                                      | [https://qsm.mypostonline.com.cn](https://qsm.mypostonline.com.cn)                               |
| NACEX Spain                                       | ES                                         | Europe   | `nacex_spain`                                       | [https://nacex.es](https://nacex.es)                                                             |
| Namibia Post                                      | NA                                         | Africa   | `namibia_post`                                      | [www.nampost.com.na](http://www.nampost.com.na)                                                  |
| Nanjing Woyuan                                    | CN                                         | Asia     | `nanjing_woyuan`                                    | [https://www.nanjingwoyuan.com](https://www.nanjingwoyuan.com)                                   |
| Naqel Express                                     | SA                                         | Asia     | `naqel_express`                                     | [https://www.naqelexpress.com](https://www.naqelexpress.com)                                     |
| Nationex                                          | CA                                         | Americas | `nationex`                                          | [https://www.nationex.com](https://www.nationex.com)                                             |
| Nationwide Express                                | MY                                         | Asia     | `nationwide_express`                                | [https://www.nationwide2u.com](https://www.nationwide2u.com)                                     |
| NCS                                               | ID                                         | Asia     | `ncs`                                               | [https://ncskurir.com](https://ncskurir.com)                                                     |
| Nepal Post                                        | NP                                         | Asia     | `nepal_post`                                        | [www.gpo.gov.np](http://www.gpo.gov.np)                                                          |
| New Zealand Couriers                              | NZ                                         | Oceania  | `new_zealand_couriers`                              | [https://www.nzcouriers.co.nz](https://www.nzcouriers.co.nz)                                     |
| New Zealand Post                                  | NZ                                         | Oceania  | `new_zealand_post`                                  | [www.nzpost.co.nz](http://www.nzpost.co.nz)                                                      |
| Neway Transport                                   | AU                                         | Oceania  | `neway_transport`                                   | [https://newaytransport.com](https://newaytransport.com)                                         |
| Newegg Express                                    | US                                         | Americas | `newegg_express`                                    | [https://www.neweggexpress.com](https://www.neweggexpress.com)                                   |
| Nexive (TNT Post Italy)                           | IT                                         | Europe   | `nexive`                                            | [www.nexive.it](http://www.nexive.it)                                                            |
| Next Smart Ship                                   | CN                                         | Asia     | `next_smart_ship`                                   | [https://fulfill.nextsmartship.com](https://fulfill.nextsmartship.com)                           |
| Nhans Solutions                                   | SG                                         | Asia     | `nhans_solutions`                                   | [https://nhans-solutions.com](https://nhans-solutions.com)                                       |
| Nhat Tin Logistics                                | VN                                         | Asia     | `nhat_tin_logistics`                                | [https://ntlogistics.vn](https://ntlogistics.vn)                                                 |
| Nicaragua Post                                    | NI                                         | Americas | `nicaragua_post`                                    | [www.correos.gob.ni](http://www.correos.gob.ni)                                                  |
| Niger Post                                        | NE                                         | Africa   | `niger_post`                                        | [www.nigerposte.net](http://www.nigerposte.net)                                                  |
| Nigerian Post / Nipost                            | NG                                         | Africa   | `nigerian_post`                                     | [www.nipost.gov.ng](http://www.nipost.gov.ng)                                                    |
| Nightline                                         | IE                                         | Europe   | `nightline`                                         | [https://www.nightline.ie](https://www.nightline.ie)                                             |
| Nikos                                             | TH                                         | Asia     | `nikos`                                             | [https://www.nikoslogistics.com](https://www.nikoslogistics.com)                                 |
| NiM Express                                       | TH                                         | Asia     | `nim_express`                                       | [https://www.nimexpress.com](https://www.nimexpress.com)                                         |
| NimbusPost                                        | IN                                         | Asia     | `nimbuspost`                                        | [https://ordr.live](https://ordr.live)                                                           |
| Ninja Van Indonesia                               | ID                                         | Asia     | `ninja_van_indonesia`                               | [https://www.ninjaxpress.co](https://www.ninjaxpress.co)                                         |
| Ninja Van International                           | SG,MY,ID,MM,TH,PH,VN                       | Asia     | `ninja_van_international`                           | [https://www.ninjavan.co](https://www.ninjavan.co)                                               |
| Ninja Van Malaysia                                | MY                                         | Asia     | `ninja_van_malaysia`                                | [https://www.ninjavan.co](https://www.ninjavan.co)                                               |
| Ninja Van Philippines                             | PH                                         | Asia     | `ninja_van_philippines`                             | [https://www.ninjavan.co](https://www.ninjavan.co)                                               |
| Ninja Van Singapore                               | SG                                         | Asia     | `ninja_van_singapore`                               | [www.ninjavan.co](http://www.ninjavan.co)                                                        |
| Ninja Van Thailand                                | TH                                         | Asia     | `ninja_van_thailand`                                | [https://www.ninjavan.co](https://www.ninjavan.co)                                               |
| Ninja Van Vietnam                                 | VN                                         | Asia     | `ninja_van_vietnam`                                 | [https://www.ninjavan.co](https://www.ninjavan.co)                                               |
| Norfolk Post                                      | NF                                         | Oceania  | `norfolk_post`                                      | [www.norfolkisland.gov.nf](http://www.norfolkisland.gov.nf)                                      |
| Norsk Global                                      | GB                                         | Europe   | `norsk_global`                                      | [https://www.norsk-global.com](https://www.norsk-global.com)                                     |
| North Russia Supply Chain                         | CN                                         | Asia     | `north_russia_supply_chain`                         | [https://8256.kingtrans.cn](https://8256.kingtrans.cn)                                           |
| Nova Poshta                                       | UA                                         | Europe   | `nova_poshta`                                       | [https://novaposhta.ua](https://novaposhta.ua)                                                   |
| Nox Germany                                       | DE                                         | Europe   | `nox_germany`                                       | [https://tcs.app.nox.express](https://tcs.app.nox.express)                                       |
| NYT SUPPLY CHAIN LOGISTICS Co                     | CN                                         | Asia     | `nyt_supply_chain_logistics`                        | [https://nyt100.com/](https://nyt100.com/)                                                       |
| OCA Argentina                                     | AR                                         | Americas | `oca_argentina`                                     | [https://www.oca.com.ar](https://www.oca.com.ar)                                                 |
| OCS ANA Group                                     | JP                                         | Asia     | `ocs_ana_group`                                     | [https://webcsw.ocs.co.jp](https://webcsw.ocs.co.jp)                                             |
| OCS Worldwide                                     | GB                                         | Europe   | `ocs_worldwide`                                     | [https://www.ocsworldwide.co.uk](https://www.ocsworldwide.co.uk)                                 |
| Old Dominion Freight Line                         | GB                                         | Europe   | `old_dominion_freight_line`                         | [https://www.odfl.com](https://www.odfl.com)                                                     |
| Olive                                             | US                                         | Americas | `olive`                                             | [https://www.shopolive.com](https://www.shopolive.com)                                           |
| Oman Post                                         | OM                                         | Asia     | `oman_post`                                         | [www.omanpost.om](http://www.omanpost.om)                                                        |
| Omni Parcel                                       | HK                                         | Asia     | `omni_parcel`                                       | [https://track.omniparcel.com](https://track.omniparcel.com)                                     |
| Omniva                                            | EE                                         | Europe   | `omniva`                                            | [https://www.omniva.ee](https://www.omniva.ee)                                                   |
| Omniva Estonia                                    | EE                                         | Europe   | `omniva_estonia`                                    | [https://www.omniva.ee](https://www.omniva.ee)                                                   |
| Omniva Latvia                                     | LV                                         | Europe   | `omniva_latvia`                                     | [https://www.omniva.lv](https://www.omniva.lv)                                                   |
| Omniva Lithuania                                  | LT                                         | Europe   | `omniva_lithuania`                                  | [https://www.omniva.ee](https://www.omniva.ee)                                                   |
| One World Express                                 | CN                                         | Asia     | `one_world_express`                                 | [https://www.oneworldexpress.cn](https://www.oneworldexpress.cn)                                 |
| OPT-NC                                            | NC                                         | Oceania  | `opt_nc`                                            | [www.opt.nc](http://www.opt.nc)                                                                  |
| Optima Overnight                                  | US                                         | Americas | `optima_overnight`                                  | [https://shipoptima.com](https://shipoptima.com)                                                 |
| Orange Connex                                     | CN                                         | Asia     | `orange_connex`                                     | [https://www.orangeconnex.com](https://www.orangeconnex.com)                                     |
| OSM Worldwide                                     | US                                         | Americas | `osm_worldwide`                                     | [https://www.osmworldwide.com](https://www.osmworldwide.com)                                     |
| Austrian Post Express                             | AU                                         | Europe   | `austrian_post_express`                             | [www.post.at](http://www.post.at)                                                                |
| Austrian Post Registered                          | AU                                         | Europe   | `austrian_post_registered`                          | [https://www.post.at/en/index.php](https://www.post.at/en/index.php)                             |
| Overseas Express                                  | HR                                         | Europe   | `overseas_express`                                  | [https://tracking.overseas.hr](https://tracking.overseas.hr)                                     |
| P2P / FedEx Cross Border                          | GB                                         | Europe   | `fedex_cross_border`                                | [https://www.p2pmailing.co.uk/en-gb/trakpak](https://www.p2pmailing.co.uk/en-gb/trakpak)         |
| Pack & Send Australia                             | AU                                         | Oceania  | `pack_send_australia`                               | [https://www.packsend.com.au/](https://www.packsend.com.au/)                                     |
| Packeta                                           | CZ                                         | Europe   | `packeta`                                           | [https://tracking.packeta.com](https://tracking.packeta.com)                                     |
| PACKFLEET                                         | GB                                         | Europe   | `packfleet`                                         | [https://app.packfleet.com](https://app.packfleet.com)                                           |
| Packlink                                          | ES                                         | Europe   | `packlink`                                          | [https://www.packlink.es](https://www.packlink.es)                                               |
| Pago Logistics                                    | CN                                         | Asia     | `pago_logistics`                                    | [https://pago.itdida.com](https://pago.itdida.com)                                               |
| Pakistan Post                                     | PK                                         | Asia     | `pakistan_post`                                     | [www.pakpost.gov.pk](http://www.pakpost.gov.pk)                                                  |
| PAKTRAC                                           | US                                         | Americas | `paktrac`                                           | [https://paktrac.com](https://paktrac.com)                                                       |
| Palestine Post                                    | PS                                         | Asia     | `palestine_post`                                    | [www.palpost.ps](http://www.palpost.ps)                                                          |
| Pandion                                           | US                                         | Americas | `pandion`                                           | [https://tracking.pandionpro.com](https://tracking.pandionpro.com)                               |
| Pandu Logistics                                   | ID                                         | Asia     | `pandu_logistics`                                   | [https://www.pandulogistics.com](https://www.pandulogistics.com)                                 |
| Panther Premium                                   | US                                         | Americas | `panther_premium`                                   | [https://arcb.com](https://arcb.com)                                                             |
| Panther UK                                        | GB                                         | Europe   | `panther`                                           | [https://www.panthergroup.co.uk/](https://www.panthergroup.co.uk/)                               |
| Paquetexpress                                     | MX                                         | Americas | `paquetexpress`                                     | [https://www.paquetexpress.com.mx](https://www.paquetexpress.com.mx)                             |
| Parcel Connect                                    | AU                                         | Oceania  | `parcel_connect`                                    | [https://www.parcelconnect.com.au](https://www.parcelconnect.com.au)                             |
| Parcel Post Singapore                             | SG                                         | Asia     | `parcel_post_singapore`                             | [https://www.parcelpost.com.sg](https://www.parcelpost.com.sg)                                   |
| Parcel Right                                      | AU                                         | Oceania  | `parcel_right`                                      | [https://portal.parcelright.com.au](https://portal.parcelright.com.au)                           |
| Parcel To Post                                    | MY                                         | Asia     | `parcel_to_post`                                    | [https://parceltopost.com](https://parceltopost.com)                                             |
| Parcelhub                                         | GB                                         | Europe   | `parcelhub`                                         | [https://web.parcelhub.net](https://web.parcelhub.net)                                           |
| PARCLL                                            | US                                         | Americas | `parcll`                                            | [https://www.parclltrack.com](https://www.parclltrack.com)                                       |
| Pargo                                             | ZA                                         | Africa   | `pargo`                                             | [https://pargo.co.za](https://pargo.co.za)                                                       |
| Park N Parcel                                     | SG                                         | Asia     | `park_n_parcel`                                     | [https://tracking.parknparcel.com](https://tracking.parknparcel.com)                             |
| Payo                                              | PH                                         | Asia     | `payo`                                              | [https://payo.asia](https://payo.asia)                                                           |
| PayPal Package                                    | CN                                         | Asia     | `paypal_package`                                    | [https://www.ppbyb.com](https://www.ppbyb.com)                                                   |
| PBT                                               | NZ                                         | Oceania  | `pbt`                                               | [https://www.pbt.com](https://www.pbt.com)                                                       |
| PFC Express                                       | CN                                         | Asia     | `pfc_express`                                       | [https://www.pfcexpress.com](https://www.pfcexpress.com)                                         |
| PFL Logistics                                     | AU                                         | Oceania  | `pfl_logistics`                                     | [https://www.pflogistics.com.au](https://www.pflogistics.com.au)                                 |
| Philippine Post                                   | PH                                         | Asia     | `philippine_post`                                   | [https://tracking.phlpost.gov.ph](https://tracking.phlpost.gov.ph)                               |
| PICK UP                                           | HK                                         | Asia     | `pick_up`                                           | [https://hk.pickupp.io](https://hk.pickupp.io)                                                   |
| PICK UP Singapore                                 | SG                                         | Asia     | `pick_up_singapore`                                 | [https://sg.pickupp.io](https://sg.pickupp.io)                                                   |
| Pickrr                                            | IN                                         | Asia     | `pickrr`                                            | [https://pickrr.com](https://pickrr.com)                                                         |
| Pilot Freight Services                            | US                                         | Americas | `pilot_freight_services`                            | [https://www.pilotdelivers.com](https://www.pilotdelivers.com)                                   |
| Ping An Da Tengfei Express                        | CN                                         | Asia     | `ping_an_da_tengfei_express`                        | [https://www.padtf.com](https://www.padtf.com)                                                   |
| Pitney Bowes                                      | US                                         | Americas | `pitney_bowes`                                      | [https://www.pitneybowes.com/us](https://www.pitneybowes.com/us)                                 |
| PITT OHIO                                         | US                                         | Americas | `pitt_ohio`                                         | [https://pittohio.com](https://pittohio.com)                                                     |
| Planète Courrier                                 | FR                                         | Europe   | `planete_courrier`                                  | [https://www.planetecourrier.com/](https://www.planetecourrier.com/)                             |
| Plycon Transportation Group                       | US                                         | Americas | `plycon_transportation_group`                       | [https://track.plyconvanlines.com](https://track.plyconvanlines.com)                             |
| PNG Post                                          | PG                                         | Oceania  | `png_post`                                          | [www.postpng.com.pg](http://www.postpng.com.pg)                                                  |
| Poczta Polska                                     | PL                                         | Europe   | `poczta_polska`                                     | [https://www.poczta-polska.pl](https://www.poczta-polska.pl)                                     |
| Poland Post                                       | PL                                         | Europe   | `poland_post`                                       | [https://emonitoring.poczta-polska.pl](https://emonitoring.poczta-polska.pl)                     |
| Pony express                                      | RU                                         | Europe   | `pony_express`                                      | [https://www.ponyexpress.ru](https://www.ponyexpress.ru)                                         |
| Portal PostNord                                   | DK,FI,SE,NO                                | Europe   | `portal_postnord`                                   | [https://portal.postnord.com](https://portal.postnord.com)                                       |
| Portugal Seur                                     | PT,ES                                      | Europe   | `portugal_seur`                                     | [https://www.seur.com](https://www.seur.com)                                                     |
| Pos Indonesia                                     | ID                                         | Asia     | `pos_indonesia`                                     | [https://www.posindonesia.co.id](https://www.posindonesia.co.id)                                 |
| Post Haste                                        | NZ                                         | Oceania  | `post_haste`                                        | [https://www.posthaste.co.nz](https://www.posthaste.co.nz)                                       |
| Post One                                          | BG                                         | Europe   | `post_one`                                          | [https://postone.eu](https://postone.eu)                                                         |
| Post Serbia                                       | RS                                         | Europe   | `post_serbia`                                       | [https://www.posta.rs](https://www.posta.rs)                                                     |
| Post11                                            | EE                                         | Europe   | `post11`                                            | [https://www.post11.com](https://www.post11.com)                                                 |
| Post56                                            | CN                                         | Asia     | `post56`                                            | [https://www.post56.cn](https://www.post56.cn)                                                   |
| Posta Plus                                        | KW                                         | Asia     | `posta_plus`                                        | [https://www.postaplus.com](https://www.postaplus.com)                                           |
| Poșta Română                                   | RO                                         | Europe   | `posta_romana`                                      | [www.posta-romana.ro](http://www.posta-romana.ro)                                                |
| Poste Italiane                                    | IT                                         | Europe   | `poste_italiane`                                    | [www.poste.it](http://www.poste.it)                                                              |
| Posten Norge / Norway Post                        | NO                                         | Europe   | `norway_post`                                       | [www.posten.no](http://www.posten.no)                                                            |
| PostNord                                          | SE,DK,FI,NO                                |          | `postnord`                                          | [https://www.postnord.com](https://www.postnord.com)                                             |
| PostNord Denmark / Denmark Post                   | DK                                         | Europe   | `denmark_post`                                      | [https://www.postnord.dk/en](https://www.postnord.dk/en)                                         |
| PostNord Norway                                   | NO                                         | Europe   | `postnord_norway`                                   | [https://my.postnord.no](https://my.postnord.no)                                                 |
| PostNord Sweden / Sweden Post                     | SE                                         | Europe   | `sweden_post`                                       | [https://www.postnord.se/](https://www.postnord.se/)                                             |
| PPL/ Professional Parcel Logistic                 | CZ                                         | Europe   | `ppl`                                               | [https://www.ppl.cz/aktualni-informace](https://www.ppl.cz/aktualni-informace)                   |
| Primetime                                         | AT                                         | Europe   | `primetime`                                         | [https://www.dpd-business.at](https://www.dpd-business.at)                                       |
| Pro Carrier                                       | GB                                         | Europe   | `pro_carrier`                                       | [https://tracking.weareprocarrier.com](https://tracking.weareprocarrier.com)                     |
| Professional Couriers                             | IN                                         | Asia     | `professional_couriers`                             | [https://www.tpcindia.com](https://www.tpcindia.com)                                             |
| Profit Fields (EWS)                               | CN                                         | Asia     | `profit_fields`                                     | [https://epost.8dt.com/index.html](https://epost.8dt.com/index.html)                             |
| PTS Worldwide                                     | TR                                         | Asia     | `pts_worldwide`                                     | [https://wp.pts.net](https://wp.pts.net)                                                         |
| PTT Posta                                         | TR                                         | Asia     | `ptt_posta`                                         | [https://gonderitakip.ptt.gov.tr](https://gonderitakip.ptt.gov.tr)                               |
| Purolator                                         | CA                                         | Americas | `purolator`                                         | [www.purolator.com](http://www.purolator.com)                                                    |
| Q-Post/Qatar Post                                 | QA                                         | Asia     | `qatar_post`                                        | [www.qpost.com.qa](http://www.qpost.com.qa)                                                      |
| Quantium Solutions                                | HK,SG                                      | Asia     | `quantium_solutions`                                | [https://quantiumsolutions.com](https://quantiumsolutions.com)                                   |
| Quickfish                                         | CN                                         | Asia     | `quickfish`                                         | [https://www.iquickfish.com](https://www.iquickfish.com)                                         |
| Quickpac                                          | DE                                         | Europe   | `quickpac`                                          | [https://www.quickpac.ch](https://www.quickpac.ch)                                               |
| QuickReliable Courier Service                     | PH                                         | Asia     | `quickreliable_courier_service`                     | [https://track.quickreliable.ph](https://track.quickreliable.ph)                                 |
| Quiet Platforms                                   | US                                         | Americas | `quiet_platforms`                                   | [https://www.quietplatforms.com](https://www.quietplatforms.com)                                 |
| Quiqup                                            | AE                                         | Asia     | `quiqup`                                            | [https://track-parcel.quiqup.com](https://track-parcel.quiqup.com)                               |
| Qwintry                                           | RU                                         | Europe   | `qwintry`                                           | [https://logistics.qwintry.com](https://logistics.qwintry.com)                                   |
| Qxpress                                           | SG                                         | Asia     | `qxpress`                                           | [https://www.qxpress.asia](https://www.qxpress.asia)                                             |
| Qyun Express                                      | CN                                         | Asia     | `qyun_express`                                      | [https://www.qyunexpress.com](https://www.qyunexpress.com)                                       |
| Raben Group                                       | DE                                         | Europe   | `raben_group`                                       | [https://oftc.myraben.com](https://oftc.myraben.com)                                             |
| RAF Philippines                                   | PH                                         | Asia     | `raf_philippines`                                   | [https://ws88.ffdx.net](https://ws88.ffdx.net)                                                   |
| RaidereX                                          | SG                                         | Asia     | `raiderex`                                          | [https://raiderex.com](https://raiderex.com)                                                     |
| RAM                                               | ZA                                         | Africa   | `ram`                                               | [https://www.ram.co.za](https://www.ram.co.za)                                                   |
| Red Carpet Logistics                              | ID                                         | Asia     | `red_carpet_logistics`                              | [https://www.rcl.co.id](https://www.rcl.co.id)                                                   |
| Redur Spain                                       | ES                                         | Europe   | `redur_spain`                                       | [https://www.redur.es](https://www.redur.es)                                                     |
| Relay Technology                                  | GB                                         | Europe   | `relay_technology`                                  | [https://track.relaytech.co](https://track.relaytech.co)                                         |
| Remax                                             | SK                                         | Europe   | `remax`                                             | [https://www.remax.sk](https://www.remax.sk)                                                     |
| RETS                                              | CN                                         | Asia     | `rets`                                              | [https://www.ets-express.com](https://www.ets-express.com)                                       |
| Rhenus Logistics                                  | DE                                         | Europe   | `rhenus_logistics`                                  | [https://rhenus-homedelivery-clientlogin.co.uk](https://rhenus-homedelivery-clientlogin.co.uk)   |
| Rincos                                            | KR                                         | Asia     | `rincos`                                            | [https://www.rincos.co.kr](https://www.rincos.co.kr)                                             |
| RL Carriers                                       | US,CA                                      | Americas | `rl_carriers`                                       | [https://www.rlcarriers.com](https://www.rlcarriers.com)                                         |
| Roadbull                                          | SG                                         | Asia     | `roadbull`                                          | [https://www.roadbull.com](https://www.roadbull.com)                                             |
| Roadie                                            | US                                         | Americas | `roadie`                                            | [https://track.roadie.com](https://track.roadie.com)                                             |
| Roadrunner Transport Service                      | US                                         | Americas | `roadrunner_transport_service`                      | [https://tools.rrts.com](https://tools.rrts.com)                                                 |
| Rocket Parcel International                       | KR                                         | Asia     | `rocket_parcel_international`                       | [https://www.rocketparcel.com](https://www.rocketparcel.com)                                     |
| Royal Mail                                        | GB                                         | Europe   | `royal_mail`                                        | [www.royalmail.com](http://www.royalmail.com)                                                    |
| Royal Shipments                                   | PL                                         | Europe   | `royal_shipments`                                   | [https://royalshipments.com](https://royalshipments.com)                                         |
| RPD2man Deliveries                                | GB                                         | Europe   | `rpd2man_deliveries`                                | [www.rpd2man.com](http://www.rpd2man.com)                                                        |
| RPX Indonesia                                     | ID                                         | Asia     | `rpx_indonesia`                                     | [https://www.rpx.co.id](https://www.rpx.co.id)                                                   |
| RPX Online                                        | HK                                         | Asia     | `rpx_online`                                        | [https://tracking.linexsolutions.com](https://tracking.linexsolutions.com)                       |
| Rush                                              | ZA                                         | Africa   | `rush`                                              | [https://www.rush.co.za](https://www.rush.co.za)                                                 |
| Russian Post                                      | RU                                         | Europe   | `russian_post`                                      | [www.russianpost.ru](http://www.russianpost.ru)                                                  |
| Ruston                                            | CN                                         | Asia     | `ruston`                                            | [https://www.ruston.cc](https://www.ruston.cc)                                                   |
| Rwanda Post                                       | RW                                         | Africa   | `rwanda_post`                                       | [https://i-posita.rw](https://i-posita.rw)                                                       |
| RXO                                               | US                                         | Americas | `rxo`                                               | [https://track.rxo.com](https://track.rxo.com)                                                   |
| RZY Express                                       | SG                                         | Asia     | `rzy_express`                                       | [https://rzyexpress.com.sg](https://rzyexpress.com.sg)                                           |
| S.F Express                                       | CN,HK                                      | Asia     | `sf_express`                                        | [www.sf-express.com](http://www.sf-express.com)                                                  |
| S.F International                                 | CN                                         | Asia     | `sf_international`                                  | [www.sfb2c.com](http://www.sfb2c.com)                                                            |
| Safexpress                                        | IN                                         | Asia     | `safexpress`                                        | [https://www.safexpress.com](https://www.safexpress.com)                                         |
| Sagawa                                            | JP                                         | Asia     | `sagawa`                                            | [https://www.sagawa-exp.co.jp](https://www.sagawa-exp.co.jp)                                     |
| SAIA FREIGHT                                      | US                                         | Americas | `saia_freight`                                      | [https://www.saia.com](https://www.saia.com)                                                     |
| Saigon Post                                       | VN                                         | Asia     | `saigon_post`                                       | [https://tracuu.saigonpost.vn](https://tracuu.saigonpost.vn)                                     |
| Sailpost                                          | IT                                         | Europe   | `sailpost`                                          | [https://www.sailpost.it](https://www.sailpost.it)                                               |
| Saint Helena Post                                 | SH                                         | Africa   | `saint_helena_post`                                 | [www.postoffice.gov.sh](http://www.postoffice.gov.sh)                                            |
| Saint Lucia Post                                  | LC                                         | Americas | `saint_lucia_post`                                  | [https://www.stluciapostal.com](https://www.stluciapostal.com)                                   |
| Samoa Post                                        | WS                                         | Oceania  | `samoa_post`                                        | samoapost.ws                                                                                     |
| San Marino Post                                   | SM                                         | Europe   | `san_marino_post`                                   | [https://www.poste.sm](https://www.poste.sm)                                                     |
| SAP Express                                       | ID                                         | Asia     | `sap_express`                                       | [https://www.sap-express.id](https://www.sap-express.id)                                         |
| Saudi Post                                        | SA                                         | Asia     | `saudi_post`                                        | [https://www.sp.com.sa](https://www.sp.com.sa)                                                   |
| Sber Logistics                                    | RU                                         | Europe   | `sber_logistics`                                    | [https://sberlogistics.ru](https://sberlogistics.ru)                                             |
| Scan Global Logistics                             | DK                                         | Europe   | `scan_global_logistics`                             | [https://scanstatus.scangl.com](https://scanstatus.scangl.com)                                   |
| Schmelz Transport & Logistik                      | DE                                         | Europe   | `schmelz_transport_logistik`                        | [https://www.schmelz.com/](https://www.schmelz.com/)                                             |
| Scudex Express                                    | IN                                         | Asia     | `scudex_express`                                    | [https://www.scudexexpress.com](https://www.scudexexpress.com)                                   |
| SDH                                               |                                            |          | `sdh`                                               | [https://www.sdh-scm.com](https://www.sdh-scm.com)                                               |
| SDK Express                                       | CN                                         | Asia     | `sdk_express`                                       | [https://www.sdk-express.cn](https://www.sdk-express.cn)                                         |
| SecuraEX                                          | IN                                         | Asia     | `securaex`                                          | [https://securaex.com](https://securaex.com)                                                     |
| SEFL                                              | US                                         | Americas | `sefl`                                              | [https://sefl.com](https://sefl.com)                                                             |
| SEKO Logistics                                    | HK                                         | Asia     | `seko_logistics`                                    | [https://harmony.myseko.com](https://harmony.myseko.com)                                         |
| Sendex                                            | MX                                         | Americas | `sendex`                                            | [https://www.sendex.mx](https://www.sendex.mx)                                                   |
| Sending                                           | ES                                         | Europe   | `sending`                                           | [https://www.sending.es](https://www.sending.es)                                                 |
| Sendit                                            | TH                                         | Asia     | `sendit`                                            | [https://tracking.sendit.asia](https://tracking.sendit.asia)                                     |
| SENHONG INTERNATIONAL LOGISTICS                   | CN                                         | Asia     | `senhong_international_logistics`                   | [https://www.showl.com](https://www.showl.com)                                                   |
| Sequoia                                           | BR                                         | Americas | `sequoia`                                           | [https://portalvesta.sequoialog.com.br](https://portalvesta.sequoialog.com.br)                   |
| Serpost                                           | PE                                         | Americas | `serpost`                                           | [https://clientes.serpost.com.pe](https://clientes.serpost.com.pe)                               |
| Servientrega Colombia                             | CO                                         | Americas | `servientrega_colombia`                             | [https://www.servientrega.com](https://www.servientrega.com)                                     |
| Servientrega Ecuador                              | ES                                         | Europe   | `servientrega_ecuador`                              | [https://www.servientrega.com.ec](https://www.servientrega.com.ec)                               |
| Servientrega Panama                               | PA                                         | Americas | `servientrega_panama`                               | [https://www.servientrega.com.pa](https://www.servientrega.com.pa)                               |
| Setel Express                                     | MY                                         | Asia     | `setel_express`                                     | [https://track.setel.com](https://track.setel.com)                                               |
| Seychelles Post                                   | SC                                         | Africa   | `seychelles_post`                                   | [www.seychellespost.gov.sc](http://www.seychellespost.gov.sc)                                    |
| SFC                                               | CN                                         | Asia     | `sfc`                                               | [https://www.sendfromchina.com](https://www.sendfromchina.com)                                   |
| SFC-SendfromChina                                 | CN                                         | Asia     | `sfc`                                               | [https://www.sendfromchina.com/](https://www.sendfromchina.com/)                                 |
| SGT Corriere Espresso                             | IT                                         | Europe   | `sgt_corriere_espresso`                             | [https://my.sgt.it](https://my.sgt.it)                                                           |
| Shadowfax                                         | IN                                         | Asia     | `shadowfax`                                         | [https://www.shadowfax.in](https://www.shadowfax.in)                                             |
| Shanghai Hongshan International Logistics         | CN                                         | Asia     | `shanghai_hongshan_international_logistics`         | [https://www.17feia.com](https://www.17feia.com)                                                 |
| Shenzhen Deqi Cross-border Supply Chain           | CN                                         | Asia     | `shenzhen_deqi`                                     | [https://web.tpdex.com/](https://web.tpdex.com/)                                                 |
| Shenzhen Longben Tianxia                          | CN                                         | Asia     | `shenzhen_longben_tianxia`                          | [https://www.lbtxkd.com](https://www.lbtxkd.com)                                                 |
| Shenzhen Zhongyou Express International Logistics | CN                                         | Asia     | `shenzhen_zhongyou_express_international_logistics` | [https://www.zyouexpress.com](https://www.zyouexpress.com)                                       |
| Ship It Asia                                      |                                            |          | `ship_it_asia`                                      | [https://viewider.com](https://viewider.com)                                                     |
| Shipa Delivery                                    | KW,SA,AE                                   | Asia     | `shipa_delivery`                                    | [https://tracking.shipadelivery.com](https://tracking.shipadelivery.com)                         |
| ShipEntegra                                       | TR                                         | Asia     | `shipentegra`                                       | [https://track.shipentegra.com](https://track.shipentegra.com)                                   |
| Shippit                                           | AU                                         | Oceania  | `shippit`                                           | [https://www.shippit.com](https://www.shippit.com)                                               |
| Shiprocket                                        | IN                                         | Asia     | `shiprocket`                                        | [https://shiprocket.co](https://shiprocket.co)                                                   |
| Shiptor                                           | RU                                         | Europe   | `shiptor`                                           | [https://shiptor.ru](https://shiptor.ru)                                                         |
| ShipX                                             | US                                         | Americas | `shipx`                                             | [https://www.shipx.com](https://www.shipx.com)                                                   |
| Shopee Xpress Indonesia                           | ID                                         | Asia     | `shopee_xpress_indonesia`                           | [https://spx.co.id](https://spx.co.id)                                                           |
| Shopee Xpress Malaysia                            | MY                                         | Asia     | `shopee_xpress_malaysia`                            | [https://shopeexpress.com.my](https://shopeexpress.com.my)                                       |
| Shopee Xpress Philippines                         | PH                                         | Asia     | `shopee_xpress_philippines`                         | [https://spx.ph](https://spx.ph)                                                                 |
| Shopee Xpress Thailand                            | TH                                         | Asia     | `shopee_xpress_thailand`                            | [https://spx.co.th](https://spx.co.th)                                                           |
| Shopee Xpress Vietnam                             | VN                                         | Asia     | `shopee_xpress_vietnam`                             | [https://spx.vn](https://spx.vn)                                                                 |
| SHREE NANDAN COURIER                              | IN                                         | Asia     | `shree_nandan_courier`                              | [https://shreenandancourier.com](https://shreenandancourier.com)                                 |
| Shree Tirupati                                    | IN                                         | Asia     | `shree_tirupati`                                    | [https://www.shreetirupaticourier.net](https://www.shreetirupaticourier.net)                     |
| Shypmax                                           | IN                                         | Asia     | `shypmax`                                           | [https://tracklite.in](https://tracklite.in)                                                     |
| Sicepat                                           | ID                                         | Asia     | `sicepat`                                           | [https://www.sicepat.com](https://www.sicepat.com)                                               |
| Sierra Leone Post                                 | SL                                         | Africa   | `sierra_leone_post`                                 | [www.salpost.sl](http://www.salpost.sl)                                                          |
| SimplyPost                                        | SG                                         | Asia     | `simplypost`                                        | [https://www.jtexpress.sg](https://www.jtexpress.sg)                                             |
| Sin Global Express                                | ID                                         | Asia     | `sin_global_express`                                | [https://singlobal-express.com](https://singlobal-express.com)                                   |
| Singapore Post / Speedpost                        | SG                                         | Asia     | `singapore_post`                                    | [https://www.singpost.com/track-items](https://www.singpost.com/track-items)                     |
| Sinotrans Express                                 | CN                                         | Asia     | `sinotrans_express`                                 | [https://www.sinoex.com.cn](https://www.sinoex.com.cn)                                           |
| Siodemka                                          | PL                                         | Europe   | `siodemka`                                          | [https://www.siodemka.com](https://www.siodemka.com)                                             |
| Sisel                                             | US,CH                                      | Americas | `sisel`                                             | [https://www.sisel.net](https://www.sisel.net)                                                   |
| Skroutz AE                                        | GR                                         | Europe   | `skroutz_ae`                                        | [https://www.skroutzlastmile.gr](https://www.skroutzlastmile.gr)                                 |
| SKYBOX                                            | TH                                         | Asia     | `skybox`                                            | [https://get.attskybox.com](https://get.attskybox.com)                                           |
| Skynet Asia Pacific                               | SG                                         | Asia     | `skynet_asia_pacific`                               | [https://www.skynetasiapacific.com](https://www.skynetasiapacific.com)                           |
| SkyNet Malaysia                                   | MY                                         | Asia     | `skynet_malaysia`                                   | [https://www.skynet.com.my](https://www.skynet.com.my)                                           |
| SkyNet Worldwide Express                          | US                                         | Americas | `skynet_worldwide_express`                          | [https://sky.skynet.net](https://sky.skynet.net)                                                 |
| SkyNet Worldwide Express UK                       | GB                                         | Europe   | `skynet_worldwide_express_uk`                       | [https://www.skynetworldwide.com](https://www.skynetworldwide.com)                               |
| Slovakia Post                                     | SK                                         | Europe   | `slovakia_post`                                     | [www.posta.sk](http://www.posta.sk)                                                              |
| Slovenia Post                                     | SI                                         | Europe   | `slovenia_post`                                     | [https://sledenje.posta.si](https://sledenje.posta.si)                                           |
| SmartCat                                          | CN                                         | Asia     | `smartcat`                                          | [https://viphm56.com](https://viphm56.com)                                                       |
| Smartr Logistics                                  | IN                                         | Asia     | `smartr_logistics`                                  | [https://smartr.in](https://smartr.in)                                                           |
| Smooth Couriers                                   | HK                                         | Asia     | `smooth_couriers`                                   | [https://app.smoothparcel.com](https://app.smoothparcel.com)                                     |
| Smooth Express                                    | TH                                         | Asia     | `smooth_express`                                    | [https://www.smoothexpress.com](https://www.smoothexpress.com)                                   |
| SMSA Express                                      | SA                                         | Asia     | `smsa_express`                                      | [https://www.smsaexpress.com](https://www.smsaexpress.com)                                       |
| SNGT                                              | IN                                         | Asia     | `sngt`                                              | [https://sngtgroup.com](https://sngtgroup.com)                                                   |
| SNT Global                                        | MY                                         | Asia     | `snt_global`                                        | [https://ets.sntglobal.com](https://ets.sntglobal.com)                                           |
| Solomon Post                                      | SB                                         | Oceania  | `solomon_post`                                      | [www.solomonpost.com.sb](http://www.solomonpost.com.sb)                                          |
| Sonic Transportation & Logistics                  | US                                         | Americas | `sonic_transportation_logistics`                    | [https://www.sonictl.com/index.asp](https://www.sonictl.com/index.asp)                           |
| South African Post                                | ZA                                         | Africa   | `south_african_post`                                | [https://www.postoffice.co.za](https://www.postoffice.co.za)                                     |
| Southeastern Freight Lines                        | US                                         | Americas | `southeastern_freight_lines`                        | [https://www.sefl.com](https://www.sefl.com)                                                     |
| Southern China Express                            | CN                                         | Asia     | `southern_china_express`                            | [https://www.yuntupost.com](https://www.yuntupost.com)                                           |
| Southwest Air Cargo                               | US                                         | Americas | `southwest_air_cargo`                               | [https://www.swacargo.com](https://www.swacargo.com)                                             |
| Spanish Seur                                      | ES,PT                                      | Europe   | `spanish_seur`                                      | [https://www.seur.com](https://www.seur.com)                                                     |
| Specialised Freight                               | ZA                                         | Africa   | `specialised_freight`                               | [https://tracking.parcelperfect.com](https://tracking.parcelperfect.com)                         |
| Spee-Dee Delivery Service                         | US                                         | Americas | `spee_dee_delivery`                                 | [https://speedeedeliver](https://speedeedeliver) y.com/                                          |
| Speed Couriers                                    | GR                                         | Europe   | `speed_couriers`                                    | [https://speedcouriers.gr](https://speedcouriers.gr)                                             |
| Speedex Greece                                    | GR                                         | Europe   | `speedex_greece`                                    | [https://www.speedex.gr](https://www.speedex.gr)                                                 |
| Speedlink                                         | VN                                         | Asia     | `speedlink`                                         | [https://speedlink.vn](https://speedlink.vn)                                                     |
| SpeedPak                                          | CN                                         | Asia     | `speedpak`                                          | [https://speedpak.com](https://speedpak.com)                                                     |
| SpeedX                                            |                                            |          | `speedx`                                            | [https://tracking.speedx.io](https://tracking.speedx.io)                                         |
| Speedy Bulgaria                                   | BG                                         | Europe   | `speedy_bulgaria`                                   | [https://speedy.bg](https://speedy.bg)                                                           |
| SPOTON Logistics                                  | IN                                         | Asia     | `spoton_logistics`                                  | [https://web1.spoton.co.in](https://web1.spoton.co.in)                                           |
| Spring                                            | BE,FR,DE,HU,IT,NL,PL,RU, ES,CH,GB,HK,SG,CA | Europe   | `spring`                                            | [https://www.mailingtechnology.com](https://www.mailingtechnology.com)                           |
| Sprint Pack                                       | CN                                         | Asia     | `sprint_pack`                                       | [https://track.sprintpack.com.cn](https://track.sprintpack.com.cn)                               |
| Sprinter                                          | HU                                         | Europe   | `sprinter`                                          | [https://www.pickpackpont.hu](https://www.pickpackpont.hu)                                       |
| SRE Korea                                         | KR                                         | Asia     | `sre_korea`                                         | [https://www.srekorea.co.kr](https://www.srekorea.co.kr)                                         |
| Sri Lanka Post                                    | LK                                         | Asia     | `sri_lanka_post`                                    | [www.slpost.gov.lk](http://www.slpost.gov.lk)                                                    |
| St. Kitts & Nevis Post                            | KN                                         | Americas | `st_kitts_nevis_post`                               | [www.post.gov.kn](http://www.post.gov.kn)                                                        |
| Stallion Express                                  | CA                                         | Americas | `stallion_express`                                  | [https://stallionexpress.ca](https://stallionexpress.ca)                                         |
| Star Track Express                                | AU                                         | Oceania  | `star_track_express`                                | [https://startrack.com.au](https://startrack.com.au)                                             |
| Starken                                           | CL                                         | Americas | `starken`                                           | [https://www.starken.cl](https://www.starken.cl)                                                 |
| Step Forward Freight                              | HK                                         | Asia     | `step_forward_freight`                              | [https://stepforwardfs.com](https://stepforwardfs.com)                                           |
| STO Express                                       | CN                                         | Asia     | `sto_express`                                       | [https://www.sto.cn](https://www.sto.cn)                                                         |
| STONE3PL                                          | CN                                         | Asia     | `stone3pl`                                          | [https://www.stone3pl.com](https://www.stone3pl.com)                                             |
| Streck Transport                                  | DE                                         | Europe   | `streck_transport`                                  | [https://streck.trackandtrace.conizi.io](https://streck.trackandtrace.conizi.io)                 |
| Sudan Post                                        | SD                                         | Africa   | `sudan_post`                                        | [https://globaltracktrace.ptc.post](https://globaltracktrace.ptc.post)                           |
| SunJEX                                            | CN                                         | Asia     | `sunjex`                                            | [https://www.sunjex.com](https://www.sunjex.com)                                                 |
| SUNYOU                                            | CN                                         | Asia     | `sunyou`                                            | [https://www.sypost.net](https://www.sypost.net)                                                 |
| Super Parcel                                      |                                            |          | `super_parcel`                                      | [https://track-sp.com](https://track-sp.com)                                                     |
| Surpost                                           | SR                                         | Americas | `surpost`                                           | [https://www.surpost.com](https://www.surpost.com)                                               |
| Sutton Transport                                  | US                                         | Americas | `sutton_transport`                                  | [https://portal.suttontrans.com](https://portal.suttontrans.com)                                 |
| SUXESS LOGISTIC                                   | AT,HU,DE                                   |          | `suxess_logistic`                                   | [https://suxesslogistic.com](https://suxesslogistic.com)                                         |
| SVG Post                                          | VC                                         | Americas | `svg_post`                                          | [www.svgpost.gov.vc](http://www.svgpost.gov.vc)                                                  |
| Swaziland Post                                    | SZ                                         | Africa   | `swaziland_post`                                    | [https://globaltracktrace.ptc.post](https://globaltracktrace.ptc.post)                           |
| Swftbox                                           | AE                                         | Asia     | `swftbox`                                           | [https://t.swftbox.com](https://t.swftbox.com)                                                   |
| Swiftpost                                         | CA                                         | Americas | `swiftpost`                                         | [https://www.swiftpost.com](https://www.swiftpost.com)                                           |
| Swiship                                           | GB                                         | Europe   | `swiship`                                           | [https://www.swiship.com](https://www.swiship.com)                                               |
| Swiship DE                                        | DE                                         | Europe   | `swiship_de`                                        | [https://www.swiship.de](https://www.swiship.de)                                                 |
| Swiship UK                                        | GB                                         | Europe   | `swiship_uk`                                        | [https://www.swiship.co.uk](https://www.swiship.co.uk)                                           |
| Swiss Post                                        | CH                                         | Europe   | `swiss_post`                                        | [https://service.post.ch](https://service.post.ch)                                               |
| Swyft Logistics                                   | PK                                         | Asia     | `swyft_logistics`                                   | [https://parceltracking.swyftlogistics.com](https://parceltracking.swyftlogistics.com)           |
| Syrian Post                                       | SY                                         | Asia     | `syrian_post`                                       | [www.syrianpost.gov.sy](http://www.syrianpost.gov.sy)                                            |
| T Cat/Taqbin Taiwan                               | TW                                         | Asia     | `t_cat`                                             | [https://www.t-cat.com.tw/](https://www.t-cat.com.tw/)                                           |
| Tai Wan Global Business                           | TW                                         | Asia     | `tai_wan_global_business`                           | [https://login.global-business.com.tw](https://login.global-business.com.tw)                     |
| Taipei Hongjiu Express                            | TW                                         | Asia     | `taipei_hongjiu_express`                            | [https://www.taipeiforever.com](https://www.taipeiforever.com)                                   |
| Take Send                                         | CN                                         | Asia     | `take_send`                                         | [https://k5.takesend.com](https://k5.takesend.com)                                               |
| Tanzania Post                                     | TZ                                         | Africa   | `tanzania_post`                                     | [https://www.posta.co.tz](https://www.posta.co.tz)                                               |
| TAQBIN Hong Kong                                  | HK                                         | Asia     | `taqbin_hong_kong`                                  | [https://hk.ta-q-bin.com](https://hk.ta-q-bin.com)                                               |
| TAQBIN International                              | JP                                         | Asia     | `taqbin_international`                              | [https://ype.yamatoparcel.co.jp](https://ype.yamatoparcel.co.jp)                                 |
| TAQBIN Malaysia                                   | MY                                         | Asia     | `taqbin_malaysia`                                   | [https://my.ta-q-bin.com](https://my.ta-q-bin.com)                                               |
| TAQBIN Singapore                                  | SG                                         | Asia     | `taqbin_singapore`                                  | [https://sg.ta-q-bin.com](https://sg.ta-q-bin.com)                                               |
| TCC                                               | ES                                         | Europe   | `tcc`                                               | [https://www.tcc.com.co](https://www.tcc.com.co)                                                 |
| TCK Express                                       | SG                                         | Asia     | `tck_express`                                       | [https://tracking.frontierforce.com](https://tracking.frontierforce.com)                         |
| TCS                                               | PK                                         | Asia     | `tcs`                                               | [https://www.tcsexpress.com](https://www.tcsexpress.com)                                         |
| Team Global Express                               | AU                                         | Oceania  | `team_global_express`                               | [https://www.myteamge.com](https://www.myteamge.com)                                             |
| Tele Post                                         | GL                                         | Americas | `tele_post`                                         | [https://telepost.gl](https://telepost.gl)                                                       |
| Teleport                                          | MY,SG,TH,PH,IN,ID,CN                       | Asia     | `teleport`                                          | [https://teleport.delivery](https://teleport.delivery)                                           |
| Teliway SIC Express                               | FR                                         | Europe   | `teliway_sic_express`                               | [https://sic.teliway.com](https://sic.teliway.com)                                               |
| TFL                                               | CN                                         | Asia     | `tfl`                                               | [https://www.tflcn.com](https://www.tflcn.com)                                                   |
| TForce Final Mile                                 | US,CA                                      | Americas | `tforce_final_mile`                                 | [https://direct.tfesg.com](https://direct.tfesg.com)                                             |
| TForce Freight                                    | US                                         | Americas | `tforce_freight`                                    | [https://www.tforcefreight.com](https://www.tforcefreight.com)                                   |
| TGX                                               | HK                                         | Asia     | `tgx`                                               | [https://www.tgxpress.com](https://www.tgxpress.com)                                             |
| Thabit Logistics                                  | SA                                         | Asia     | `thabit_logistics`                                  | [https://thabit-logistics.com](https://thabit-logistics.com)                                     |
| Thailand Post                                     | TH                                         | Asia     | `thailand_post`                                     | [https://track.thailandpost.co.th](https://track.thailandpost.co.th)                             |
| The Courier Guy                                   | ZA                                         | Africa   | `the_courier_guy`                                   | [https://www.thecourierguy.co.za](https://www.thecourierguy.co.za)                               |
| TIG Freight                                       | AU                                         | Oceania  | `tig_freight`                                       | [https://trackmyparcel.com.au](https://trackmyparcel.com.au)                                     |
| Tiki                                              | ID                                         | Asia     | `tiki`                                              | [https://tiki.id](https://tiki.id)                                                               |
| TIM KOP                                           | ME                                         | Europe   | `tim_kop`                                           | [https://www.timkop.me](https://www.timkop.me)                                                   |
| Tinghao                                           | CN                                         | Asia     | `tinghao`                                           | [https://www.tinghaowl.com](https://www.tinghaowl.com)                                           |
| TIPSA                                             | ES                                         | Europe   | `tipsa`                                             | [https://www.tip-sa.com](https://www.tip-sa.com)                                                 |
| TMF Express                                       | AU                                         | Oceania  | `tmf_express`                                       | [https://tfmxpress.com.au](https://tfmxpress.com.au)                                             |
| TNT                                               | NL                                         | Europe   | `tnt`                                               | [www.tnt.com](http://www.tnt.com)                                                                |
| TNT Australia                                     | AU                                         | Oceania  | `tnt_australia`                                     | [https://www.tntexpress.com.au](https://www.tntexpress.com.au)                                   |
| TNT France                                        | FR                                         | Europe   | `tnt_france`                                        | [https://www.tnt.fr](https://www.tnt.fr)                                                         |
| TNT Italy                                         | IT                                         | Europe   | `tnt_italy`                                         | [https://www.tnt.it](https://www.tnt.it)                                                         |
| TNT UK                                            | GB                                         | Europe   | `tnt_uk`                                            | [https://www.tnt.com](https://www.tnt.com)                                                       |
| TNT-Click Italy                                   | IT                                         | Europe   | `tnt_click_italy`                                   | [www.tnt-click.it](http://www.tnt-click.it)                                                      |
| To My Door                                        | AU                                         | Oceania  | `to_my_door`                                        | [https://www.tomydoor.com.au](https://www.tomydoor.com.au)                                       |
| Toll NZ                                           | AU                                         | Oceania  | `toll_nz`                                           | [https://fasttracker-nz.tollgroup.com](https://fasttracker-nz.tollgroup.com)                     |
| Toll Priority                                     | AU                                         | Oceania  | `toll_priority`                                     | [https://www.tollpriority.com.au](https://www.tollpriority.com.au)                               |
| Tolos                                             | KP                                         | Asia     | `tolos`                                             | [https://www.tolos.asia](https://www.tolos.asia)                                                 |
| TONDA GLOBAL                                      | CN                                         | Asia     | `tonda_global`                                      | [https://www.tarrive.com](https://www.tarrive.com)                                               |
| Tonga Post                                        | TO                                         | Oceania  | `tonga_post`                                        | [www.tongapost.to](http://www.tongapost.to)                                                      |
| Top Delivery                                      | RU                                         | Europe   | `top_delivery`                                      | [https://www.topdelivery.ru](https://www.topdelivery.ru)                                         |
| Top Ideal Express                                 | CN                                         | Asia     | `top_ideal_express`                                 | [https://www.esdex.com](https://www.esdex.com)                                                   |
| Topdser                                           | US                                         | Americas | `topdser`                                           | [https://www.tdexpress.net](https://www.tdexpress.net)                                           |
| TopYou                                            | CN                                         | Asia     | `topyou`                                            | [https://szty56.com](https://szty56.com)                                                         |
| TP Logistics (Thai Parcel)                        | TH                                         | Asia     | `tp_logistics`                                      | [https://thaiparcels.com/](https://thaiparcels.com/)                                             |
| Trackon Couriers                                  | IN                                         | Asia     | `trackon_couriers`                                  | [https://trackon.in](https://trackon.in)                                                         |
| TrakPak                                           | GB                                         | Europe   | `trakpak`                                           | [https://www.trackmytrakpak.com](https://www.trackmytrakpak.com)                                 |
| Trans-o-flex                                      | DE                                         | Europe   | `trans_o_flex`                                      | [https://www.trans-o-flex.com/en/](https://www.trans-o-flex.com/en/)                             |
| Transportes de Carga                              | GT                                         | Americas | `transportes_de_carga`                              | [https://www.transportesdecarga.com.gt](https://www.transportesdecarga.com.gt)                   |
| TT Post                                           | TT                                         | Americas | `tt_post`                                           | [https://ttpost.net](https://ttpost.net)                                                         |
| TTK Express                                       | CN                                         | Asia     | `ttk_express`                                       | [https://www.ttkdex.com](https://www.ttkdex.com)                                                 |
| Tuffnells Parcels Express                         | GB                                         | Europe   | `tuffnells_parcels_express`                         | [https://www.tuffnells.co.uk](https://www.tuffnells.co.uk)                                       |
| TYP                                               | IT                                         | Europe   | `typ`                                               | [https://tracking.typ.delivery](https://tracking.typ.delivery)                                   |
| UBI Logistics Australia                           | AU                                         | Oceania  | `ubi_logistics_australia`                           | [https://www.au.gotoubi.com](https://www.au.gotoubi.com)                                         |
| UBI Smart Parcel                                  | CN                                         | Asia     | `ubi_smart_parcel`                                  | [https://smartparcel.gotoubi.com](https://smartparcel.gotoubi.com)                               |
| UES Ecommerce                                     | UY                                         | Americas | `ues_ecommerce`                                     | [https://www.ues.com.uy](https://www.ues.com.uy)                                                 |
| Uganda Post                                       | UG                                         | Africa   | `uganda_post`                                       | [www.ugapost.co.ug](http://www.ugapost.co.ug)                                                    |
| UK Mail                                           | GB                                         | Europe   | `uk_mail`                                           | [https://track.dhlparcel.co.uk](https://track.dhlparcel.co.uk)                                   |
| Ukraine EMS                                       | UA                                         | Europe   | `ukraine_ems`                                       | dpsz.ua                                                                                          |
| UkrPoshta                                         | UA                                         | Europe   | `ukrposhta`                                         | [https://track.ukrposhta.ua](https://track.ukrposhta.ua)                                         |
| Unex                                              | RU                                         | Europe   | `unex`                                              | [https://unex.su](https://unex.su)                                                               |
| Uni Uni                                           | CA,US                                      | Americas | `uni_uni`                                           | [https://www.uniuni.com](https://www.uniuni.com)                                                 |
| United Cargo                                      | US                                         | Americas | `united_cargo`                                      | [https://www.unitedcargo.com](https://www.unitedcargo.com)                                       |
| United Delivery                                   | US                                         | Americas | `uds`                                               | [https://www.uniteddeliveryservice.com/index.ht](https://www.uniteddeliveryservice.com/index.ht) |
| UPS                                               | US                                         | Americas | `ups`                                               | [www.ups.com](http://www.ups.com)                                                                |
| UrbanFox                                          | SG                                         | Asia     | `urbanfox`                                          | [https://dp.urbanfox.asia](https://dp.urbanfox.asia)                                             |
| Urbify                                            | DE                                         | Europe   | `urbify`                                            | [https://urbify.de](https://urbify.de)                                                           |
| Usky Express                                      | CN                                         | Asia     | `usky_express`                                      | [https://www.uskyexpress.com](https://www.uskyexpress.com)                                       |
| USPS                                              | US                                         | Americas | `usps`                                              | [www.usps.com](http://www.usps.com)                                                              |
| Uzbekistan Post                                   | UZ                                         | Asia     | `uzbekistan_post`                                   | [www.pochta.uz](http://www.pochta.uz)                                                            |
| Vamaship                                          | IN                                         | Asia     | `vamaship`                                          | [https://www.vamaship.com](https://www.vamaship.com)                                             |
| VAMOX                                             | ES                                         | Europe   | `vamox`                                             | [https://tracking.vamox.io](https://tracking.vamox.io)                                           |
| Vanuatu Post                                      | VU                                         | Oceania  | `vanuatu_post`                                      | [https://www.vanuatupost.vu](https://www.vanuatupost.vu)                                         |
| VASP Expresso                                     | PT                                         | Europe   | `vasp_expresso`                                     | [https://online.vaspexpresso.pt](https://online.vaspexpresso.pt)                                 |
| Vatican Post                                      | VA                                         | Europe   | `vatican_post`                                      | [www.vaticanstate.va](http://www.vaticanstate.va)                                                |
| VEHO                                              | US                                         | Americas | `veho`                                              | [https://shipveho.com/](https://shipveho.com/)                                                   |
| Venipak Lithuania                                 | LT                                         | Europe   | `venipak_lithuania`                                 | [https://venipak.lt](https://venipak.lt)                                                         |
| Vietnam Airlines                                  | VN                                         | Asia     | `vietnam_airlines`                                  | [https://www.cargoupdate.com](https://www.cargoupdate.com)                                       |
| Vietnam Post                                      | VN                                         | Asia     | `vietnam_post`                                      | [https://www.vnpost.vn](https://www.vnpost.vn)                                                   |
| Viettel Post                                      | VN                                         | Asia     | `viettel_post`                                      | [https://old.viettelpost.com.vn](https://old.viettelpost.com.vn)                                 |
| VNCPOST                                           | VN                                         | Asia     | `vncpost`                                           | [https://vncpost.com](https://vncpost.com)                                                       |
| Wahana                                            | ID                                         | Asia     | `wahana`                                            | [https://www.wahana.com](https://www.wahana.com)                                                 |
| Wanb Express                                      | CN                                         | Asia     | `wanb_express`                                      | [https://tracking.wanbexpress.com](https://tracking.wanbexpress.com)                             |
| We Pick Up                                        | PT                                         | Europe   | `we_pick_up`                                        | [https://www.wepickup.pt](https://www.wepickup.pt)                                               |
| We Post                                           | MY                                         | Asia     | `we_post`                                           | [https://www.wepost.com.my](https://www.wepost.com.my)                                           |
| WeDo Logistics                                    | CN                                         | Asia     | `wedo_logistics`                                    | [https://www.wedoexpress.com](https://www.wedoexpress.com)                                       |
| Whats Ship                                        | HK                                         | Asia     | `whats_ship`                                        | [https://www.whatsship.com](https://www.whatsship.com)                                           |
| Whistl                                            | GB                                         | Europe   | `whistl`                                            | [https://trackmyitem.whistl.co.uk](https://trackmyitem.whistl.co.uk)                             |
| WHT Express                                       | CN                                         | Asia     | `wht_express`                                       | [https://www.whtexpress.com](https://www.whtexpress.com)                                         |
| Winit                                             | CN                                         | Asia     | `winit`                                             | [https://track.winit.com.cn](https://track.winit.com.cn)                                         |
| Winlink Logistics/ Vnlin                          | HK                                         | Asia     | `winlink_logistics`                                 | [https://www.winlinklogistics.com/index.html](https://www.winlinklogistics.com/index.html)       |
| Wise Express                                      | CN                                         | Asia     | `wise_express`                                      | [https://www.shwise.cn](https://www.shwise.cn)                                                   |
| Wiseloads                                         | IE                                         | Europe   | `wiseloads`                                         | [https://wiseloads.dmsmatrix.net](https://wiseloads.dmsmatrix.net)                               |
| WishPost                                          | CN                                         | Asia     | `wishpost`                                          | [https://www.wishpost.cn](https://www.wishpost.cn)                                               |
| Wizmo                                             | US                                         | Americas | `wizmo`                                             | [https://portal.shipwizmo.com](https://portal.shipwizmo.com)                                     |
| WLS Spedition                                     | DE                                         | Europe   | `wls_spedition`                                     | [https://websped.wls-spedition.de](https://websped.wls-spedition.de)                             |
| WMYC                                              | CN                                         | Asia     | `wmyc`                                              | [https://wms.wmycc.com](https://wms.wmycc.com)                                                   |
| wnDirect                                          | GB                                         | Europe   | `wndirect`                                          | [https://uktracking.asendia.com](https://uktracking.asendia.com)                                 |
| Worldnet International                            |                                            |          | `worldnet_international`                            | [https://tracking.lightening.co](https://tracking.lightening.co)                                 |
| Wyngs                                             | MY                                         | Asia     | `wyngs`                                             | [https://www.wyngs-my.com](https://www.wyngs-my.com)                                             |
| X Express Brza Posta                              | BA                                         | Europe   | `x_express_brza_posta`                              | [https://www.x-express.ba](https://www.x-express.ba)                                             |
| XDE Logistics                                     | PH                                         | Asia     | `xde_logistics`                                     | [https://www.xde.com.ph](https://www.xde.com.ph)                                                 |
| Xingyuan Supply Chain Co.                         | CN                                         | Asia     | `xingyuan_supply_chain`                             | new\.sz-tianma.com                                                                               |
| Xingyunyi Logistics                               | CN                                         | Asia     | `xingyunyi_logistics`                               | [https://wms.xingyunyi.cn](https://wms.xingyunyi.cn)                                             |
| Xinshu Logistics                                  | CN                                         | Asia     | `xinshu_logistics`                                  | [https://xs-exp.com](https://xs-exp.com)                                                         |
| XL Express                                        | AU                                         | Oceania  | `xl_express`                                        | [https://my.xlexpress.com.au](https://my.xlexpress.com.au)                                       |
| Xpedigo                                           | CA                                         | Americas | `xpedigo`                                           | [https://tracking.xpedigo.com](https://tracking.xpedigo.com)                                     |
| XPO                                               | US                                         | Americas | `xpo`                                               | [https://ext-web.ltl-xpo.com](https://ext-web.ltl-xpo.com)                                       |
| XPOST                                             | PH                                         | Asia     | `xpost`                                             | [https://www.xpost.ph](https://www.xpost.ph)                                                     |
| XpressBees                                        | IN                                         | Asia     | `xpressbees`                                        | [https://www.xpressbees.com](https://www.xpressbees.com)                                         |
| XQ Logistics                                      | CN                                         | Asia     | `xq_logistics`                                      | [https://www.xqkjwl.com](https://www.xqkjwl.com)                                                 |
| XYY Logistics                                     | CN                                         | Asia     | `xyy_logistics`                                     | [https://wms.xingyunyi.cn](https://wms.xingyunyi.cn)                                             |
| Yakit                                             | US                                         | Americas | `yakit`                                             | [https://www.yakit.com](https://www.yakit.com)                                                   |
| Yamato Japan                                      | JP                                         | Asia     | `yamato_japan`                                      | [https://track.kuronekoyamato.co.jp](https://track.kuronekoyamato.co.jp)                         |
| Yamato Singapore                                  | SG                                         | Asia     | `yamato_singapore`                                  | [https://tracking.yamatosingapore.com](https://tracking.yamatosingapore.com)                     |
| Yanwen                                            | CN                                         | Asia     | `yanwen`                                            | [https://www.yw56.com.cn](https://www.yw56.com.cn)                                               |
| YCH                                               | SG,VN                                      | Asia     | `ych`                                               | [https://etrack.ych.com](https://etrack.ych.com)                                                 |
| YDH                                               | CN                                         | Asia     | `ydh`                                               | [https://www.ydhex.com](https://www.ydhex.com)                                                   |
| Yemen Post                                        | YE                                         | Asia     | `yemen_post`                                        | [www.post.ye](http://www.post.ye)                                                                |
| YiFan Express                                     | CN                                         | Asia     | `yifan_express`                                     | [https://yifan.kingtrans.net](https://yifan.kingtrans.net)                                       |
| YiLi Express                                      | CN                                         | Asia     | `yili_express`                                      | [https://oms.yl-ru.com](https://oms.yl-ru.com)                                                   |
| Yilian (Elian) Supply Chain                       | CN                                         | Asia     | `yilian_supply_chain`                               | [https://www.elianpost.com/index.html](https://www.elianpost.com/index.html)                     |
| Yodel Direct                                      | GB                                         | Europe   | `yodel_direct`                                      | [https://www.yodeldirect.co.uk](https://www.yodeldirect.co.uk)                                   |
| Yodel International                               | GB                                         | Europe   | `yodel`                                             | [www.yodel.co.uk](http://www.yodel.co.uk)                                                        |
| YRC                                               | US                                         | Americas | `yrc`                                               | [https://www.yrc.com](https://www.yrc.com)                                                       |
| YTO Express                                       | CN                                         | Asia     | `yto_express`                                       | [https://www.ytoglobal.com](https://www.ytoglobal.com)                                           |
| Yun Express                                       | CN                                         | Asia     | `yun_express`                                       | [https://www.yuntrack.com](https://www.yuntrack.com)                                             |
| Yunda Express                                     | CN                                         | Asia     | `yunda_express`                                     | [https://www.yundaex.com](https://www.yundaex.com)                                               |
| Yusen Logistics                                   | JP                                         | Asia     | `yusen_logistics`                                   | [https://rt.yusen-logistics.com](https://rt.yusen-logistics.com)                                 |
| Yuteng                                            | CN                                         | Asia     | `yuteng`                                            | [https://www.yutengguoji.com](https://www.yutengguoji.com)                                       |
| Zajil Express Company                             | AE                                         | Asia     | `zajil_express_company`                             | [https://zajil-express.com](https://zajil-express.com)                                           |
| Zalora 7-Eleven                                   | SG                                         | Asia     | `zalora`                                            | [www.zalora.com.hk](http://www.zalora.com.hk)                                                    |
| Zambia Post                                       | ZM                                         | Africa   | `zambia_post`                                       | [www.zampost.com.zm](http://www.zampost.com.zm)                                                  |
| ZDE                                               | RU                                         | Europe   | `zde`                                               | [https://i.jde.ru](https://i.jde.ru)                                                             |
| Zeek                                              | HK                                         | Asia     | `zeek`                                              | [https://www.zeek.one](https://www.zeek.one)                                                     |
| Zimbabwe Post                                     | ZW                                         | Africa   | `zimbabwe_post`                                     | [https://ips-webtracking.zimpost.co.zw](https://ips-webtracking.zimpost.co.zw)                   |
| Zinc                                              | US                                         | Americas | `zinc`                                              | [https://tracking.link](https://tracking.link)                                                   |
| Zoom                                              | ID                                         | Asia     | `zoom`                                              | [https://zoomitnow.co](https://zoomitnow.co)                                                     |
| ZTO Express                                       | CN                                         | Asia     | `zto_express`                                       | [https://kh.zto.com](https://kh.zto.com)                                                         |
| Zufall                                            | DE                                         | Europe   | `zufall`                                            | [https://zufall.trackandtrace.conizi.io](https://zufall.trackandtrace.conizi.io)                 |
| Zyllem                                            | SG                                         | Asia     | `zyllem`                                            | [https://www.zyllem.com](https://www.zyllem.com)                                                 |

***

<br />

## Add tracking number to webhook

1. If you have not already, create a tracking [webhook](/tracking/webhooks).
   * Set the webhook **Event Type** to **Track Updated**.
   * Set the webhook **Environment** to **Production**.
   * Set the webhook **URL** to an address that can [listen to your webhook](/tracking/webhook-debugging).
2. POST the below to the [tracks endpoint](/api-reference/tracking-status/get-a-tracking-status).

```shell theme={null}
curl https://api.goshippo.com/tracks/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -d carrier="<CARRIER_TOKEN>" \
  -d tracking_number="<TRACKING_NUMBER>" \
```


# Tracking Carriers
Source: https://docs.goshippo.com/tracking/tracking-carriers

View the full list of carriers supported for parcel tracking through the Shippo API, including tokens for each carrier.

The Shippo API supports you in tracking your labels bought though Shippo as well as [label purchased outside of Shippo](/tracking/tracking#track-individual-shipments).

We support the following list of carriers for tracking.

| Carrier name              | Token              |
| ------------------------- | ------------------ |
| Airterra                  | airterra           |
| APC Postal                | apc\_postal        |
| APG                       | apg                |
| Aramex                    | aramex             |
| Asendia                   | asendia\_us        |
| Australia Post            | australia\_post    |
| Better Trucks             | better\_trucks     |
| BorderGuru                | borderguru         |
| Boxberry                  | boxberry           |
| Bring                     | bring              |
| Canada Post               | canada\_post       |
| Chronopost                | chronopost         |
| Colissimo                 | colissimo          |
| Collect+                  | collect\_plus      |
| Correos BR                | correios\_br       |
| Correos Spain             | correos\_espana    |
| Deutsche Post             | deutsche\_post     |
| DHL Benelux               | dhl\_benelux       |
| DHL eCommerce             | dhl\_ecommerce     |
| DHL Express               | dhl\_express       |
| DHL Germany               | dhl\_germany       |
| DPD DE                    | dpd\_de            |
| DPD UK                    | dpd\_uk            |
| ePostGlobal               | rr\_donnelley      |
| Estafeta                  | estafeta           |
| Evri UK                   | hermes\_uk         |
| Fastway Australia         | fastway\_australia |
| FedEx                     | fedex              |
| Globegistics              | globegistics       |
| GLS US                    | gls\_us            |
| GSO                       | gso                |
| Jitsu (formerly Axlehire) | axlehire           |
| La Poste                  | la\_poste          |
| Lasership                 | lasership          |
| LSO                       | lso                |
| Mondial Relay             | mondial\_relay     |
| Nippon Express            | nippon\_express    |
| NZ Post                   | new\_zealand\_post |
| OnTrac                    | ontrac             |
| Passport                  | passport           |
| PCF                       | pcf                |
| Pitney Bowes              | pitney\_bowes      |
| Poste Italiane            | poste\_italiane    |
| Posti                     | posti              |
| Purolator                 | purolator          |
| Royal Mail Intersoft      | royal\_mail        |
| Royal Mail SF             | royal\_mail\_sf    |
| Russian Post              | russian\_post      |
| SkyPostal                 | skypostal          |
| Stuart                    | stuart             |
| UDS                       | uds                |
| UPS                       | ups                |
| USPS                      | usps               |
| Veho                      | veho               |

<Info>
  **note**

  There are some restrictions for some carriers. Refer to our [carrier restrictions](/tracking/tracking#carrier-restrictions) guide for more information.
</Info>


# Webhook debugging
Source: https://docs.goshippo.com/tracking/webhook-debugging

Test and debug your Shippo webhooks using your own server or third-party webhook testing sites.

## Using your own server

If you have a public-facing web server and would like to view the test events as they come in, you can use this BASH one-liner (listening on port 8891). This snippet returns the HTTP 200 response we expect your endpoint to return in production.

<Info>
  **note**

  You do not need to have jq installed as this is just for pretty printing the POST Body response.
</Info>

jq formatting for webhook test listener:

`~$ while true; do { echo -e 'HTTP/1.1 200 OK\r\n'; } | nc -l 8891 | grep test | jq . ; done`

<img alt="Webhooks Debugging Screenshot" />

## Using webhook testing sites

There are many websites available to test a webhook response. You can use sites like [https://webhook-test.com/](https://webhook-test.com/) to listen for webhooks sent by Shippo.

<Info>
  **note**

  While you can test your webhooks using public services, it's important to understand that you are sharing your information with these third-parties. Only use test data. Never share production data. We recommend using [your own server](#using-your-own-server) where possible.

  The mention of a specific company or product name is solely for educational purposes and does not imply endorsement by Shippo.
</Info>

To use a service like webhook-test, copy the unique webhook URL from the site and add it as the `URL` to your Shippo webhook.

Selecting `Send sample` sends a test payload that you can view in the webhook testing site.

<img alt="webhook testing website sample" />


# Webhook metadata
Source: https://docs.goshippo.com/tracking/webhook-metadata

Attach custom metadata to transactions and tracking objects to include your own data in Shippo webhook payloads.

## Webhook metadata

Metadata is additional information you can include in many Shippo objects.
For some of these objects (`transaction`, `shipment`, and `batch`), this metadata can be very useful when handling webhook notifications because it allows you to associate your own custom data with the Shippo objects.

The following example shows how to use metadata with a transaction and the resulting webhook payload that is created.

### Create a `transaction_created` webhook

If you do not have one already, create a webhook with event type **Transaction Created** following the [setting up and testing webhooks](/tracking/webhooks#setting-up-and-testing-webhooks) guide.

### Create a transaction

Purchase a label by calling the `transactions` endpoint. Include the field `metadata` with a string containing your additional information.

```shell Create transaction request theme={null}
url --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'SHIPPO-API-VERSION: 2018-02-08' \
--data-raw '{
  "rate": "a5c9d1bec93149f5bedc3a9374b50970",
  "async": false,
  "label_file_type": "PDF",
  "metadata":"customer_ID:12, order_ID:558a"
}'
```

### Webhook payload

The Shippo API will send a webhook payload to your URL including the `metadata` you configured in your transaction.

```json theme={null}
{
  "event": "transaction_created",
  "test": true,
  "data": {
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2024-06-17T14:31:40.000Z",
    "object_updated": "2024-06-17T14:31:40.000Z",
    "object_id": "70ae8117ee1749e393f249d5b77c45e0",
    "object_owner": "mrshippo@shippo.com",
    "test": true,
    "rate": "fe9a78973c5b409498af1fd9baefbe34",
    "tracking_number": "ZW70QJC",
    "tracking_status": "UNKNOWN",
    "eta": "2024-06-22T14:31:40.347Z",
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=ZW70QJC",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "messages": [],
    "order": "7535a41cac64426fa87ebfa24ad11123",
    "metadata": "customer_ID:12, order_ID:558a",
    "parcel": "faf460225c4d49699e18384dc32a1cc6",
    "billing": {
      "payments": []
    }
  }
}
```

On receiving the webhook, you can parse the metadata and use it to update your system, notify users, or trigger other actions. For example, you might use this update to send an automated email to your customer to keep them up to date. This is a common pattern for parcel tracking. The Shippo API also supports metadata in webhooks for [tracking labels purchased outside of Shippo](/tracking/tracking#adding-metadata).

You can use metadata in this way for any of the [supported webhook event types](/tracking/webhooks#webhook-event-types).

### Webhook metadata for tracking

Metadata from a transaction does not get passed to your tracking webhook payload. You can add metadata to an existing tracking object by re-registering your tracking webhook.

Use the `tracking_number` from your transaction response along with your `carrier` and `metadata`. This `metadata` will be included in all webhook payloads associated with tracking updates for this `tracking_number`.

```shell theme={null}
 curl https://api.goshippo.com/tracks/ \
  --header "Authorization: ShippoToken <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "carrier": "usps",
    "tracking_number": "9205590164917312751089",
    "metadata": "Order 000123"
 }'
```


# Webhook security
Source: https://docs.goshippo.com/tracking/webhook-security

Secure your Shippo webhooks using IP allowlists, self-generated URL tokens, or HMAC-based message authentication.

Shippo has three options that you can use to help you protect the integrity of your [webhook](/tracking/webhooks).
The three options for securing your webhook are as follows.

* [Inbound IP allowlist](#inbound-ip-allowlist)
* [Self-generated tokens](#self-generated-tokens)
* [HMAC](#hmac-security)

You can choose any one of these options or combine multiple options.

## Inbound IP allowlist

The first option is to add Shippo’s IP range to your inbound allowlist and ignore messages that did not originate from those addresses. Add the following Shippo IP addresses to your inbound allowlist.

### US region

```
52.4.41.98
52.23.121.194
52.44.110.80
54.81.253.187
54.81.255.221
```

### EU region

```
34.248.247.69
34.253.119.130
52.214.174.64
54.72.179.250
```

## Self-generated tokens

You can add self-generated tokens to the end of the request URL query parameter like [https://myurl.com/?token=123abc](https://myurl.com/?token=123abc) when you create your webhook using the Shippo webapp.

To generate a webhook, follow these steps:

1. Sign in to your [Shippo account](https://goshippo.com/login/)
2. In the left hand menu, click **Setting**, then **API**
3. In the API menu, find the **Webhooks** section
4. Click **Add webhook** to create a new webhook
5. Enter your **Event Type**, **Mode**, and **URL**.
6. In the URL field, add your self-generated token to the end of your tracking URL, in the format ?token=123abc, where “123abc”, is your self-generated token.
7. Click **Save**

<img alt="webhook UI token string" />

You will be able to see the same token as a query parameter returned in your webhook POST call. This method is secure as long as you protect the storage of the expected token.

You can add a self-generated token to an existing webhook by clicking **Edit**.

<img alt="webhook edit button in UI" />

## HMAC Security

Hash-based Message Authentication Code [HMAC](https://en.wikipedia.org/wiki/HMAC) security is a combination of a security hash shared from you to Shippo and a second from Shippo to you. This is more secure because the tokens are known systemically to each recipient of a request or response and block attacks such as a man in the middle.

To set up HMAC for webhooks, email your account manager with the following subject line or contact our [sales team](https://goshippo.com/become-a-shippo-partner) adding the following to the `Additional Details:` section.

```
HMAC Webhook Setup for <insert name here>
```

Shippo will setup a token and our solutions team will contact you to setup the token exchange. This can take up to 10 business days to complete.

### Verifying your webhooks HMAC

Use the following bash script to verify your HMAC has been configured correctly for your webhook.

```bash theme={null}
#!/bin/bash

# Received from Shippo solutions team
secret='<YOUR_SHIPPO_HMAC_SECRET>'

# identify signature header & body payload
payload=$(cat)


# $HTTP_SHIPPO_AUTH_SIGNATURE: t=1688493073,v1=24036c00f9adad56ad83504e5dce63fe0a248631865a89fe9adb9494f6dc7c0b
sig_header=$'<YOUR_HTTP_SHIPPO_AUTH_SIGNATURE>'

# extract timestamp and signature from header
timestamp=$(echo $sig_header | cut -d',' -f1 | cut -d'=' -f2)
signature=$(echo $sig_header | cut -d',' -f2 | cut -d'=' -f2)

# create "signed payload" string
signed_payload_string="${timestamp}.${payload}"

# compute the expected signature
test_signature=$(echo -n "${signed_payload_string}" | openssl dgst -sha256 -hmac "${secret}" | cut -d' ' -f2)

# verify the request signature matches the expected signature
if [ "${signature}" != "${test_signature}" ]; then
	echo 'Invalid signature!'
fi

```


# Webhooks
Source: https://docs.goshippo.com/tracking/webhooks

Set up Shippo webhooks to receive automatic notifications for tracking updates, label creation, and batch purchases.

Instead of fetching updates for tracking, batch labels, and transactions manually, you can use Shippo webhooks to get notified when a status changes.

## Setting up and testing webhooks

You can set up webhooks on the [Shippo API Portal](https://portal.goshippo.com/api-config/webhooks). This page also allows you to test webhooks with a sample payload.

<img alt="Webhooks Sample Screenshot" />

<Info>
  **note**

  The URL you set when creating your webhook must be less than 200 characters long.
</Info>

We also offer a Webhooks API to allow you to programmatically create, retrieve, edit and delete webhooks. You can [access the documentation here](/tracking/creating-webhooks). The Webhooks API is currently in beta and the endpoints might change. Please reach out to [support@shippo.com](mailto:product@shippo.com) if you have questions.

<Info>
  **note**

  When you purchase a label in Shippo, Shippo automatically creates a webhook for tracking that label. You can view the details of that webhook in the [Shippo API Portal](https://portal.goshippo.com/api-config/webhooks) or using the [webhooks endpoint](/tracking/creating-webhooks#retrieving-all-active-webhooks).
</Info>

## Webhook event types

* `transaction_created`: sent whenever a transaction is created in your account. The POST request body will contain a JSON of the [Transaction object](/api-reference/transactions/list-all-shipping-labels) that was created.

* `transaction_updated`: sent whenever a transaction is updated in your account. The POST request body will contain a JSON of the [Transaction object](/api-reference/transactions/list-all-shipping-labels) that was updated.

* `track_updated`: for tracking status updates. The POST request body will contain a JSON of the [Tracking object](/api-reference/tracking-status/get-a-tracking-status). If you are interested in the types of events returned within the track\_updated field, please view more details [here](/tracking/tracking#event-definitions).
  * We regularly request updates from each carrier's system to get the latest status of shipments. Whenever there's a change in status, we immediately send an update to the webhook via a POST request. The frequency of these updates varies among carriers due to the rate limits set by each carrier. On average, users can expect updates within 2 hours of an event occurring. For some carriers this time is much lower.
  * For API version 2017-03-29 and older, the body will contain the [Transaction object](/api-reference/transactions/list-all-shipping-labels) if the label was created on Shippo.

* `batch_created`: for creating the Batch object that contain Batch Shipments. This process is done asynchronously, so first you'd get an empty [Batch object](/api-reference/batches/create-a-batch) back, then Batch Shipments will be created in the background.

* `batch_purchased`: for purchasing Batch Shipments through the Batch endpoint. This request is done asynchronously as well. Once purchases are complete, you will be able to download a merged PDF containing up to 100 labels per file.

* `all`: sent when any of the supported events occur. Acts as a catch-all for events.

Additionally, the `Shippo-API-Version` header is included in all webhook responses to indicate what version of the API is being used.

## Webhook payload

The following are example webhook payloads for each webhook event type.

<CodeGroup>
  ```json {% title="track_updated" %} theme={null}
  {
    "event": "track_updated",
    "test": true,
    "data": {
      "address_from": {
        "city": "Las Vegas",
        "country": "US",
        "state": "NV",
        "zip": "89101"
      },
      "address_to": {
        "city": "Las Vegas",
        "country": "US",
        "state": "NV",
        "zip": "89101"
      },
      "carrier": "usps",
      "eta": "2019-08-24T14:15:22Z",
      "messages": [
        "string"
      ],
      "metadata": "Order 000123",
      "original_eta": "2021-07-23T00:00:00Z",
      "servicelevel": {
        "name": "Priority Mail Express",
        "terms": "string",
        "token": "usps_priority_express",
        "extended_token": "string",
        "parent_servicelevel": {
          "name": "Priority Mail Express",
          "terms": "string",
          "token": "usps_priority_express",
          "extended_token": "string"
        }
      },
      "tracking_history": [
        {
          "location": {
            "city": "Las Vegas",
            "country": "US",
            "state": "NV",
            "zip": "89101"
          },
          "object_created": "2019-08-24T14:15:22Z",
          "object_id": "string",
          "object_updated": "2019-08-24T14:15:22Z",
          "status": "DELIVERED",
          "substatus": {
            "code": "information_received",
            "text": "Information about the package received.",
            "action_required": false
          },
          "status_date": "2016-07-23T00:00:00Z",
          "status_details": "Your shipment has been delivered at the destination mailbox."
        }
      ],
      "tracking_number": "9205590164917312751089",
      "tracking_status": {
        "location": {
          "city": "Las Vegas",
          "country": "US",
          "state": "NV",
          "zip": "89101"
        },
        "object_created": "2019-08-24T14:15:22Z",
        "object_id": "string",
        "object_updated": "2019-08-24T14:15:22Z",
        "status": "DELIVERED",
        "substatus": {
          "code": "information_received",
          "text": "Information about the package received.",
          "action_required": false
        },
        "status_date": "2016-07-23T00:00:00Z",
        "status_details": "Your shipment has been delivered at the destination mailbox."
      },
      "transaction": "string"
    }
  }
  ```

  ```json {% title="batch_purchased" %} theme={null}
  {
    "event": "batch_purchased",
    "test": true,
    "data": "batch # processing complete"
  }
  ```

  ```json {% title="batch_created" %} theme={null}
  {
    "event": "batch_created",
    "test": true,
    "data": "batch # created"
  }
  ```

  ```json {% title="transaction_created" %} theme={null}
  {
    "event": "transaction_created",
    "test": true,
    "data": {
      "commercial_invoice_url": "string",
      "created_by": {
        "first_name": "Shwan",
        "last_name": "Ippotle",
        "username": "shippotle@shippo.com"
      },
      "eta": "string",
      "label_file_type": "PDF_4x6",
      "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
      "messages": [
        {
          "source": "UPS",
          "code": "carrier_timeout",
          "text": "UPS API did not respond. Please try again in a few minutes."
        }
      ],
      "metadata": "string",
      "object_created": "2019-08-24T14:15:22Z",
      "object_id": "915d94940ea54c3a80cbfa328722f5a1",
      "object_owner": "shippotle@shippo.com",
      "object_state": "VALID",
      "object_updated": "2019-08-24T14:15:22Z",
      "parcel": "e94c7fdfdc7b495dbb390a28d929d90a",
      "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
      "rate": {
        "amount": "5.5",
        "amount_local": "5.5",
        "currency": "USD",
        "currency_local": "USD",
        "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
        "provider": "USPS",
        "carrier_account": "078870331023437cb917f5187429b093",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "fedex_ground"
      },
      "status": "SUCCESS",
      "test": true,
      "tracking_number": "9499907123456123456781",
      "tracking_status": "DELIVERED",
      "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
    }
  }
  ```

  ```json {% title="transaction_updated" %} theme={null}
  {
    "event": "transaction_updated",
    "test": true,
    "data": {
      "commercial_invoice_url": "string",
      "created_by": {
        "first_name": "Shwan",
        "last_name": "Ippotle",
        "username": "shippotle@shippo.com"
      },
      "eta": "string",
      "label_file_type": "PDF_4x6",
      "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
      "messages": [
        {
          "source": "UPS",
          "code": "carrier_timeout",
          "text": "UPS API did not respond. Please try again in a few minutes."
        }
      ],
      "metadata": "string",
      "object_created": "2019-08-24T14:15:22Z",
      "object_id": "915d94940ea54c3a80cbfa328722f5a1",
      "object_owner": "shippotle@shippo.com",
      "object_state": "VALID",
      "object_updated": "2019-08-24T14:15:22Z",
      "parcel": "e94c7fdfdc7b495dbb390a28d929d90a",
      "qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
      "rate": {
        "amount": "5.5",
        "amount_local": "5.5",
        "currency": "USD",
        "currency_local": "USD",
        "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
        "provider": "USPS",
        "carrier_account": "078870331023437cb917f5187429b093",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "fedex_ground"
      },
      "status": "SUCCESS",
      "test": true,
      "tracking_number": "9499907123456123456781",
      "tracking_status": "DELIVERED",
      "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
    }
  }
  ```
</CodeGroup>

## Expected webhook behavior

Shippo expects your Webhook endpoint to return a 2XX HTTP status code in a timely manner (three seconds or less) to indicate that the POST payload has been received. If your Webhook endpoint does not process the payload in a timely manner or you return a 408, 429, or 5XX status code, Shippo will retry twice. No retry is attempted upon other client error status codes (4XX).