README.md

Parcels

(parcels)

Overview

A parcel is an item you are shipping. The parcel object includes details about its physical make-up of the parcel. It includes dimensions and weight that Shippo uses to calculate rates.

Parcel Extras

The following values are supported for the extra field of the parcel object.

Available Operations

• list - List all parcels
• create - Create a new parcel
• get - Retrieve an existing parcel

list

Returns a list of all parcel objects.

Example Usage

import { Shippo } from "shippo";

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

async function run() {
  const result = await shippo.parcels.list();
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { ShippoCore } from "shippo/core.js";
import { parcelsList } from "shippo/funcs/parcelsList.js";

// Use `ShippoCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const shippo = new ShippoCore({
  apiKeyHeader: "<YOUR_API_KEY_HERE>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const res = await parcelsList(shippo);

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

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

run();

Parameters

Parameter	Type	Required	Description
page	number	➖	The page number you want to select
results	number	➖	The number of results to return per page (max 100)
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<components.ParcelPaginatedList>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

create

Creates a new parcel object.

Example Usage

import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "<YOUR_API_KEY_HERE>",
  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();

Standalone function

The standalone function version of this method:

import { ShippoCore } from "shippo/core.js";
import { parcelsCreate } from "shippo/funcs/parcelsCreate.js";

// Use `ShippoCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const shippo = new ShippoCore({
  apiKeyHeader: "<YOUR_API_KEY_HERE>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const res = await parcelsCreate(shippo, {
    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",
  });

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

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

run();

Parameters

Parameter	Type	Required	Description
request	operations.CreateParcelRequestBody	✔️	The request object to use for the request.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<components.Parcel>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

get

Returns parcel details using an existing parcel object ID (this will not return parcel details associated with un-purchased shipment/rate parcel object IDs).

Example Usage

import { Shippo } from "shippo";

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

async function run() {
  const result = await shippo.parcels.get("<value>");
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { ShippoCore } from "shippo/core.js";
import { parcelsGet } from "shippo/funcs/parcelsGet.js";

// Use `ShippoCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const shippo = new ShippoCore({
  apiKeyHeader: "<YOUR_API_KEY_HERE>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const res = await parcelsGet(shippo, "<value>");

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

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

run();

Parameters

Parameter	Type	Required	Description
parcelId	string	✔️	Object ID of the parcel
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<components.Parcel>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/