Skip to main content
POST
/
parcels
cURL
curl https://api.goshippo.com/parcels/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -d length=5 \
  -d width=5 \
  -d height=5 \
  -d distance_unit="cm" \
  -d weight=2 \
  -d mass_unit="lb" \
  -d template="" \
  -d metadata="Customer ID 123456"
import shippo
from shippo.models import components

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.parcels.create(request=components.ParcelCreateRequest(
    extra=components.ParcelExtra(
        cod=components.Cod(
            amount='5.5',
            currency='USD',
            payment_method=components.PaymentMethod.CASH,
        ),
        insurance=components.ParcelInsurance(
            amount='5.5',
            content='Laptop',
            currency='USD',
            provider=components.ParcelInsuranceProvider.UPS,
        ),
    ),
    metadata='Customer ID 123456',
    mass_unit=components.WeightUnitEnum.LB,
    weight='1',
    distance_unit=components.DistanceUnitEnum.IN,
    height='1',
    length='1',
    width='1',
))

if res is not None:
    # handle response
    pass
import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "ShippoToken <API_TOKEN>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const result = await shippo.parcels.create({
    extra: {
      cod: {
        amount: "5.5",
        currency: "USD",
        paymentMethod: "CASH",
      },
      insurance: {
        amount: "5.5",
        content: "Laptop",
        currency: "USD",
        provider: "UPS",
      },
    },
    metadata: "Customer ID 123456",
    massUnit: "lb",
    weight: "1",
    distanceUnit: "in",
    height: "1",
    length: "1",
    width: "1",
  });

  // Handle the result
  console.log(result);
}

run();
declare(strict_types=1);

require 'vendor/autoload.php';

use Shippo\API;
use Shippo\API\Models\Components;

$sdk = API\Shippo::builder()
    ->setSecurity(
        'ShippoToken <API_TOKEN>'
    )
    ->setShippoApiVersion('2018-02-08')
    ->build();



$response = $sdk->parcels->create(
    requestBody: new Components\ParcelCreateRequest(
        extra: new Components\ParcelExtra(
            cod: new Components\Cod(
                amount: '5.5',
                currency: 'USD',
                paymentMethod: Components\PaymentMethod::Cash,
            ),
            insurance: new Components\ParcelInsurance(
                amount: '5.5',
                content: 'Laptop',
                currency: 'USD',
                provider: Components\ParcelInsuranceProvider::Ups,
            ),
        ),
        metadata: 'Customer ID 123456',
        massUnit: Components\WeightUnitEnum::Lb,
        weight: '1',
        distanceUnit: Components\DistanceUnitEnum::In,
        height: '1',
        length: '1',
        width: '1',
    ),
    shippoApiVersion: '2018-02-08'

);

if ($response->parcel !== null) {
    // handle response
}
using Shippo;
using Shippo.Models.Components;

var sdk = new ShippoSDK(
    apiKeyHeader: "ShippoToken <API_TOKEN>",
    shippoApiVersion: "2018-02-08"
);

var res = await sdk.Parcels.CreateAsync(
    requestBody: CreateParcelRequestBody.CreateParcelCreateRequest(
        new ParcelCreateRequest() {
            Extra = new ParcelExtra() {
                Cod = new Cod() {
                    Amount = "5.5",
                    Currency = "USD",
                    PaymentMethod = PaymentMethod.Cash,
                },
                Insurance = new ParcelInsurance() {
                    Amount = "5.5",
                    Content = "Laptop",
                    Currency = "USD",
                    Provider = ParcelInsuranceProvider.Ups,
                },
            },
            Metadata = "Customer ID 123456",
            MassUnit = WeightUnitEnum.Lb,
            Weight = "1",
            DistanceUnit = DistanceUnitEnum.In,
            Height = "1",
            Length = "1",
            Width = "1",
        }
    ),
    shippoApiVersion: "2018-02-08"
);

// handle response
package hello.world;

import com.goshippo.shippo_sdk.Shippo;
import com.goshippo.shippo_sdk.models.components.Cod;
import com.goshippo.shippo_sdk.models.components.DistanceUnitEnum;
import com.goshippo.shippo_sdk.models.components.ParcelCreateRequest;
import com.goshippo.shippo_sdk.models.components.ParcelExtra;
import com.goshippo.shippo_sdk.models.components.ParcelInsurance;
import com.goshippo.shippo_sdk.models.components.ParcelInsuranceProvider;
import com.goshippo.shippo_sdk.models.components.PaymentMethod;
import com.goshippo.shippo_sdk.models.components.WeightUnitEnum;
import com.goshippo.shippo_sdk.models.operations.CreateParcelRequestBody;
import com.goshippo.shippo_sdk.models.operations.CreateParcelResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Shippo sdk = Shippo.builder()
                .apiKeyHeader("ShippoToken <API_TOKEN>")
                .shippoApiVersion("2018-02-08")
            .build();

        CreateParcelResponse res = sdk.parcels().create()
                .shippoApiVersion("2018-02-08")
                .requestBody(CreateParcelRequestBody.of(ParcelCreateRequest.builder()
                    .massUnit(WeightUnitEnum.LB)
                    .weight("1")
                    .distanceUnit(DistanceUnitEnum.IN)
                    .height("1")
                    .length("1")
                    .width("1")
                    .extra(ParcelExtra.builder()
                        .cod(Cod.builder()
                            .amount("5.5")
                            .currency("USD")
                            .paymentMethod(PaymentMethod.CASH)
                            .build())
                        .insurance(ParcelInsurance.builder()
                            .amount("5.5")
                            .content("Laptop")
                            .currency("USD")
                            .provider(ParcelInsuranceProvider.UPS)
                            .build())
                        .build())
                    .metadata("Customer ID 123456")
                    .build()))
                .call();

        if (res.parcel().isPresent()) {
            // handle response
        }
    }
}
const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    mass_unit: 'lb',
    weight: '1',
    distance_unit: 'in',
    height: '1',
    length: '1',
    width: '1',
    extra: {
      COD: {amount: '5.5', currency: 'USD', payment_method: 'CASH'},
      insurance: {amount: '5.5', content: 'Laptop', currency: 'USD', provider: 'UPS'},
      reference_1: '<string>',
      reference_2: '<string>'
    },
    metadata: 'Customer ID 123456'
  })
};

fetch('https://api.goshippo.com/parcels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goshippo.com/parcels"

	payload := strings.NewReader("{\n  \"mass_unit\": \"lb\",\n  \"weight\": \"1\",\n  \"distance_unit\": \"in\",\n  \"height\": \"1\",\n  \"length\": \"1\",\n  \"width\": \"1\",\n  \"extra\": {\n    \"COD\": {\n      \"amount\": \"5.5\",\n      \"currency\": \"USD\",\n      \"payment_method\": \"CASH\"\n    },\n    \"insurance\": {\n      \"amount\": \"5.5\",\n      \"content\": \"Laptop\",\n      \"currency\": \"USD\",\n      \"provider\": \"UPS\"\n    },\n    \"reference_1\": \"<string>\",\n    \"reference_2\": \"<string>\"\n  },\n  \"metadata\": \"Customer ID 123456\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
require 'uri'
require 'net/http'

url = URI("https://api.goshippo.com/parcels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mass_unit\": \"lb\",\n  \"weight\": \"1\",\n  \"distance_unit\": \"in\",\n  \"height\": \"1\",\n  \"length\": \"1\",\n  \"width\": \"1\",\n  \"extra\": {\n    \"COD\": {\n      \"amount\": \"5.5\",\n      \"currency\": \"USD\",\n      \"payment_method\": \"CASH\"\n    },\n    \"insurance\": {\n      \"amount\": \"5.5\",\n      \"content\": \"Laptop\",\n      \"currency\": \"USD\",\n      \"provider\": \"UPS\"\n    },\n    \"reference_1\": \"<string>\",\n    \"reference_2\": \"<string>\"\n  },\n  \"metadata\": \"Customer ID 123456\"\n}"

response = http.request(request)
puts response.read_body
{
  "mass_unit": "lb",
  "weight": "1",
  "distance_unit": "in",
  "height": "1",
  "length": "1",
  "width": "1",
  "extra": {
    "COD": {
      "amount": "5.5",
      "currency": "USD",
      "payment_method": "CASH"
    },
    "insurance": {
      "amount": "5.5",
      "content": "Laptop",
      "currency": "USD",
      "provider": "UPS"
    },
    "reference_1": "<string>",
    "reference_2": "<string>"
  },
  "metadata": "Customer ID 123456",
  "object_created": "2014-07-09T02:19:13.174Z",
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_owner": "shippotle@shippo.com",
  "object_state": "VALID",
  "object_updated": "2014-07-09T02:19:13.174Z",
  "test": true
}
{}

Authorizations

​
Authorization
string
header
default:ShippoToken
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Parcel details.

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
weight
string
required

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
distance_unit
enum<string>
required

The measure unit used for length, width and height.

Available options:
cm,
in,
ft,
m,
mm,
yd
Example:

"in"

​
height
string
required

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
length
string
required

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
width
string
required

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
extra
Parcel Extra · object

An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.

​
metadata
string
Example:

"Customer ID 123456"

Response

Parcel

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
weight
string
required

Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
distance_unit
enum<string>
required

The measure unit used for length, width and height.

Available options:
cm,
in,
ft,
m,
mm,
yd
Example:

"in"

​
height
string
required

Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
length
string
required

Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
width
string
required

Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.

Example:

"1"

​
extra
Parcel Extra · object

An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the extra field of the parcel object.

​
metadata
string
Example:

"Customer ID 123456"

​
object_created
string<date-time>

Date and time of Parcel creation.

Example:

"2014-07-09T02:19:13.174Z"

​
object_id
string

Unique identifier of the given Parcel object. This ID is required to create a Shipment object.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

​
object_owner
string

Username of the user who created the Parcel object.

Example:

"shippotle@shippo.com"

​
object_state
enum<string>

A Parcel will only be valid when all required values have been sent and validated successfully.

Available options:
VALID
Example:

"VALID"

​
object_updated
string<date-time>

Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given.

Example:

"2014-07-09T02:19:13.174Z"

​
template

If template is passed, length, width, height, and distance_unit are not required

Available options:
FedEx_Box_10kg,
FedEx_Box_25kg,
FedEx_Box_Extra_Large_1,
FedEx_Box_Extra_Large_2,
FedEx_Box_Large_1,
FedEx_Box_Large_2,
FedEx_Box_Medium_1,
FedEx_Box_Medium_2,
FedEx_Box_Small_1,
FedEx_Box_Small_2,
FedEx_Envelope,
FedEx_Padded_Pak,
FedEx_Pak_1,
FedEx_Pak_2,
FedEx_Tube,
FedEx_XL_Pak
​
test
boolean

Indicates whether the object has been created in test mode.