# Parcel

`Parcel` objects represent the physical container being shipped.

Dimensions can be supplied either as `length`, `width`, and `height` dimensions, or a `predefined_package` string.

`weight` is required. Some carriers also require parcel dimensions for certain services. To avoid validation errors and ensure accurate rating, include `length`, `width`, and `height` whenever available. Refer to the applicable Carrier Guides for carrier-specific requirements.

  **IMPORTANT:** Weights are in OUNCES (OZ) and go to one decimal point.

  **IMPORTANT:** Dimensions are in INCHES (IN) and go to one decimal point.

---

## Parcel object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with "prcl_" |
| object | string | "Parcel" |
| length | float (inches) | Required if width and/or height are present |
| width | float (inches) | Required if length and/or height are present |
| height | float (inches) | Required if length and/or width are present |
| predefined_package | string | Optional, one of our predefined packages |
| weight | float (oz) | Always required. Must be specified in ounces (oz). |
| created_at | datetime | When the Parcel was created |
| updated_at | datetime | When the Parcel was last updated |

Example Object:

```json
{
  "id": "prcl_e8d0eeef8b454eb5b7f2bf8a8dd2fcca",
  "object": "Parcel",
  "created_at": "2025-05-09T20:39:26Z",
  "updated_at": "2025-05-09T20:39:26Z",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "mode": "test"
}
```

---

[Content omitted: carrier services and predefined packages rendered dynamically. Review the rendered documentation for complete service level and package details.]

---

## Create a Parcel

### Example: POST /parcels

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/parcels \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "parcel": {
      "length": "20.2",
      "width": "10.9",
      "height": "5",
      "weight": "65.9"
    }
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	parcel, _ := client.CreateParcel(
		&easypost.Parcel{
			Length: 20.2,
			Width:  10.9,
			Height: 5,
			Weight: 65.9,
		},
	)

	fmt.Println(parcel)
}
```

#### Java

```java
package parcels;

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

import java.util.HashMap;

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

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("height", 5);
        params.put("width", 10.9);
        params.put("length", 20.2);
        params.put("weight", 65.9);

        Parcel parcel = client.parcel.create(params);

        System.out.println(parcel);
    }
}
```

#### C#

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

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

            EasyPost.Parameters.Parcel.Create parameters = new()
            {
                Length = 20.2,
                Width = 10.9,
                Height = 5,
                Weight = 65.9
            };

            EasyPost.Models.API.Parcel parcel = await client.Parcel.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(parcel, Formatting.Indented));
        }
    }
}
```

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const parcel = await client.Parcel.create({
    length: 20.2,
    width: 10.9,
    height: 5,
    weight: 65.9,
  });

  console.log(parcel);
})();
```

#### PHP

```php
<?php

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

$parcel = $client->parcel->create([
    'length' => 20.2,
    'width' => 10.9,
    'height' => 5,
    'weight' => 65.9
]);

echo $parcel;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

parcel = client.parcel.create(
    length=20.2,
    width=10.9,
    height=5,
    weight=65.9,
)

print(parcel)
```

#### Ruby

```ruby
require 'easypost'

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

parcel = client.parcel.create(
  length: 20.2,
  width: 10.9,
  height: 5,
  weight: 65.9,
)

puts parcel
```

Include the `weight`, and either a `predefined_package` or `length`, `width` and `height` if applicable.

[Note: This object is immutable after creation. Review the rendered documentation for details.]

---

## Retrieve a Parcel

### Example: GET /parcels/:id

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/parcels/prcl_... \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

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

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

	parcel, _ := client.GetParcel("prcl_...")

	fmt.Println(parcel)
}
```

#### Java

```java
package parcels;

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

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

        Parcel parcel = client.parcel.retrieve("prcl_...");

        System.out.println(parcel);
    }
}
```

#### C#

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

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

            EasyPost.Models.API.Parcel parcel = await client.Parcel.Retrieve("prcl_...");

            Console.WriteLine(JsonConvert.SerializeObject(parcel, Formatting.Indented));
        }
    }
}
```

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const parcel = await client.Parcel.retrieve('prcl_...');

  console.log(parcel);
})();
```

#### PHP

```php
<?php

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

$parcel = $client->parcel->retrieve('prcl_...');

echo $parcel;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

parcel = client.parcel.retrieve("prcl_...")

print(parcel)
```

#### Ruby

```ruby
require 'easypost'

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

parcel = client.parcel.retrieve('prcl_...')

puts parcel
```

Retrieve a `Parcel` by its `id`. In general you should not need to use this in your automated solution. A `Parcel` object's `id` can be inlined into the creation call to other objects. This allows you to only create one `Parcel` for each package you will be using.