### Build and Run Examples

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/examples/README.md

Build the project and then execute an example file using tsx. Ensure Node.js v18 or higher and npm are installed.

```bash
npm run build && npx tsx example.ts
```

--------------------------------

### Install Shippo JavaScript SDK

Source: https://context7.com/goshippo/shippo-javascript-sdk/llms.txt

Install the SDK using npm, pnpm, bun, or yarn.

```bash
npm add shippo
# or
pnpm add shippo
# or
bun add shippo
# or
yarn add shippo
```

--------------------------------

### Install Shippo SDK with Bun

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Install the Shippo SDK using the Bun package manager.

```bash
bun add shippo
```

--------------------------------

### Example Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/webhookpayloadtransaction.md

An example of how to use the WebhookPayloadTransaction in TypeScript.

```typescript
import { WebhookPayloadTransaction } from "shippo/models/components";

let value: WebhookPayloadTransaction = {
  data: {
    createdBy: {
      firstName: "Shwan",
      lastName: "Ippotle",
      username: "shippotle@shippo.com",
    },
    labelFileType: "PDF_4x6",
    labelUrl:
      "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.",
      },
    ],
    objectId: "915d94940ea54c3a80cbfa328722f5a1",
    objectOwner: "shippotle@shippo.com",
    parcel: "e94c7fdfdc7b495dbb390a28d929d90a",
    qrCodeUrl:
      "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    rate: "ec9f0d3adc9441449c85d315f0997fd5",
    status: "SUCCESS",
    trackingNumber: "9499907123456123456781",
    trackingStatus: "DELIVERED",
    trackingUrlProvider:
      "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
  },
};

```

--------------------------------

### Install Shippo SDK with PNPM

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Install the Shippo SDK using the pnpm package manager.

```bash
pnpm add shippo
```

--------------------------------

### Install Shippo SDK with Yarn

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Install the Shippo SDK using the Yarn package manager.

```bash
yarn add shippo
```

--------------------------------

### Install Shippo SDK with NPM

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Install the Shippo SDK using the npm package manager.

```bash
npm add shippo
```

--------------------------------

### ListRefundsRequest Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/listrefundsrequest.md

Example of how to import and initialize a ListRefundsRequest object.

```APIDOC
## ListRefundsRequest

### Description
Represents the request object for listing refunds.

### Fields
This model does not have any fields that can be directly set by the user. It is typically used as a placeholder or for internal SDK operations.

### Request Example
```typescript
import { ListRefundsRequest } from "shippo/models/operations";

let value: ListRefundsRequest = {};
```
```

--------------------------------

### shipmentsCreate Function Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/sdks/shipments/README.md

This example demonstrates how to import and use the `shipmentsCreate` function with a `ShippoCore` instance. It includes a detailed request body with various optional fields for shipment creation, such as addresses, customs declarations, carrier accounts, parcels, and extra shipment details.

```APIDOC
## shipmentsCreate

### Description
Creates a shipment object using the Shippo JavaScript SDK.

### Method
`shipmentsCreate(shippoCoreInstance, shipmentData)`

### Parameters
#### `shippoCoreInstance`
- **Type**: `ShippoCore`
- **Description**: An initialized instance of `ShippoCore`.

#### `shipmentData`
- **Type**: `object`
- **Description**: An object containing the shipment details.
  - **`metadata`** (string) - Optional - Arbitrary object to include in the request. May be a JSON string or a JavaScript object.
  - **`shipmentDate`** (string) - Optional - The date the shipment will be sent. Format: ISO 8601.
  - **`addressFrom`** (string) - Required - The ID of the address object for the sender.
  - **`addressReturn`** (string) - Optional - The ID of the address object for the return sender.
  - **`addressTo`** (string) - Required - The ID of the address object for the recipient.
  - **`customsDeclaration`** (string) - Optional - The ID of the customs declaration object.
  - **`carrierAccounts`** (array of strings) - Optional - A list of carrier account IDs to use for this shipment.
  - **`parcels`** (array of strings) - Required - A list of parcel IDs to use for this shipment.
  - **`extra`** (object) - Optional - Additional shipment details.
    - **`accountsReceivableCustomerAccount`** (object) - Optional
    - **`appropriationNumber`** (object) - Optional
    - **`billOfLadingNumber`** (object) - Optional
    - **`cod`** (object) - Optional - Cash on Delivery details.
      - **`amount`** (string) - Optional - The amount for COD.
      - **`currency`** (string) - Optional - The currency for COD.
      - **`paymentMethod`** (string) - Optional - The payment method for COD.
    - **`codNumber`** (object) - Optional
    - **`customerReference`** (object) - Optional
    - **`dealerOrderNumber`** (object) - Optional
    - **`deptNumber`** (object) - Optional
    - **`fdaProductCode`** (object) - Optional
    - **`insurance`** (object) - Optional - Insurance details.
      - **`amount`** (string) - Optional - The amount for insurance.
      - **`currency`** (string) - Optional - The currency for insurance.
    - **`invoiceNumber`** (object) - Optional
    - **`manifestNumber`** (object) - Optional
    - **`modelNumber`** (object) - Optional
    - **`partNumber`** (object) - Optional
    - **`poNumber`** (object) - Optional
    - **`productionCode`** (object) - Optional
    - **`purchaseRequestNumber`** (object) - Optional
    - **`rmaNumber`** (object) - Optional
    - **`salespersonNumber`** (object) - Optional
    - **`serialNumber`** (object) - Optional
    - **`storeNumber`** (object) - Optional
    - **`transactionReferenceNumber`** (object) - Optional

### Request Example
```javascript
import { ShippoCore } from "shippo/core.js";
import { shipmentsCreate } from "shippo/funcs/shipmentsCreate.js";

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

async function run() {
  const res = await shipmentsCreate(shippo, {
    extra: {
      accountsReceivableCustomerAccount: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      appropriationNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      billOfLadingNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      cod: {
        amount: "5.5",
        currency: "USD",
        paymentMethod: "CASH",
      },
      codNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      customerReference: {
        refSort: 1,
      },
      dealerOrderNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      deptNumber: {
        refSort: 3,
      },
      fdaProductCode: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      insurance: {
        amount: "5.5",
        currency: "USD",
      },
      invoiceNumber: {
        refSort: 2,
      },
      manifestNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      modelNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      partNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      poNumber: {
        refSort: 2,
      },
      productionCode: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      purchaseRequestNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      rmaNumber: {
        refSort: 1,
      },
      salespersonNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      serialNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      storeNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
      transactionReferenceNumber: {
        prefix: "ABC",
        value: "value",
        refSort: 1,
      },
    },
    metadata: "Customer ID 123456",
    shipmentDate: "2021-03-22T12:00:00Z",
    addressFrom: "d799c2679e644279b59fe661ac8fa488",
    addressReturn: "d799c2679e644279b59fe661ac8fa488",
    addressTo: "d799c2679e644279b59fe661ac8fa489",
    customsDeclaration: "adcfdddf8ec64b84ad22772bce3ea37a",
    carrierAccounts: [
      "065a4a8c10d24a34ab932163a1b87f52",
      "73f706f4bdb94b54a337563840ce52b0",
    ],
    parcels: [
      "<value>",
    ],
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("shipmentsCreate failed:", res.error);
  }
}

run();
```

### Response
#### Success Response (200)
- **`value`** (object) - The created shipment object.
- **`ok`** (boolean) - Indicates if the request was successful.
- **`error`** (object) - Contains error details if the request failed.

#### Response Example
(Response structure depends on the API response, typically a shipment object on success or an error object on failure.)
```

--------------------------------

### Example Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/servicelevellasershipenum.md

Demonstrates how to import and use the ServiceLevelLasershipEnum in your TypeScript code.

```APIDOC
## Example Usage

```typescript
import { ServiceLevelLasershipEnum } from "shippo/models/components";

let value: ServiceLevelLasershipEnum = "lasership_routed_delivery";
```
```

--------------------------------

### ListOrdersRequest Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/listordersrequest.md

Demonstrates how to instantiate and use the ListOrdersRequest model with example properties.

```APIDOC
## ListOrdersRequest

### Description
Represents the request object used for listing and filtering orders.

### Properties
- **orderStatus** (string[]) - Optional - An array of order statuses to filter by. Possible values include "PAID", "UNPAID", "CANCELED", "RETURNED".
- **shopApp** (string) - Optional - The name of the shop application to filter orders by.

### Example Usage
```typescript
import { ListOrdersRequest } from "shippo/models/operations";

let value: ListOrdersRequest = {
  orderStatus: [
    "PAID",
  ],
  shopApp: "Shippo",
};
```
```

--------------------------------

### UpdateWebhookRequest Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/updatewebhookrequest.md

An example demonstrating how to construct an UpdateWebhookRequest object.

```APIDOC
## UpdateWebhookRequest

### Description
Represents the request payload for updating an existing webhook.

### Fields

#### `webhookId`
- **Type**: `string`
- **Required**: Yes
- **Description**: The unique identifier of the webhook to be updated.

#### `webhookUpdateRequest`
- **Type**: `object` (WebhookUpdateRequest)
- **Required**: Yes
- **Description**: An object containing the updated details for the webhook.

##### `webhookUpdateRequest` Fields

- **`event`** (string) - Required - The event that triggers the webhook.
- **`url`** (string) - Required - The URL to which webhook notifications will be sent.
- **`active`** (boolean) - Optional - Whether the webhook is currently active.
- **`isTest`** (boolean) - Optional - Indicates if this is a test webhook.

### Request Example
```typescript
import { UpdateWebhookRequest } from "shippo/models/operations";

let value: UpdateWebhookRequest = {
  webhookId: "<id>",
  webhookUpdateRequest: {
    event: "all",
    url: "https://example.com/shippo-webhook",
    active: true,
    isTest: false,
  },
};
```
```

--------------------------------

### GetRateRequest Model Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/getraterequest.md

Example of how to instantiate and use the GetRateRequest model.

```APIDOC
## GetRateRequest

### Description
Represents the request object for retrieving a rate.

### Fields
#### rateId (string) - Required
Object ID of the rate.
```

--------------------------------

### Get Carrier Registration Status

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/sdks/carrieraccounts/README.md

Retrieves the registration status for a specific carrier account. This is useful for verifying if a carrier is ready for use or requires further setup.

```APIDOC
## GET /carrier_accounts/reg-status

### Description
Retrieves the registration status for a specific carrier account.

### Method
GET

### Endpoint
/carrier_accounts/reg-status

### Parameters
#### Query Parameters
- **carrier_provider** (string) - Required - The identifier for the carrier provider (e.g., "ups").

### Response
#### Success Response (200)
- **status** (string) - The registration status of the carrier account.
- **carrier_provider** (string) - The carrier provider identifier.

### Request Example
```javascript
shippo.carrierAccounts.getRegistrationStatus("ups");
```

### Response Example
```json
{
  "status": "registered",
  "carrier_provider": "ups"
}
```
```

--------------------------------

### Get Webhook Details

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/sdks/webhooks/README.md

This snippet shows how to retrieve the details of a specific webhook by its ID using the `webhooks.getWebhook` method. It includes initialization of the Shippo SDK and a basic example of calling the method.

```APIDOC
## getWebhook

Returns the details of a specific webhook using the webhook object ID.

### Method
`webhooks.getWebhook(webhookId: string, options?: RequestOptions): Promise<Response<Webhook, SDKError>>`

### Parameters
#### Path Parameters
- `webhookId` (string) - Required - The ID of the webhook to retrieve.

#### Options
- `options` (RequestOptions) - Optional - Used to set various options for making HTTP requests.
  - `options.fetchOptions` (RequestInit) - Optional - 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) - Optional - Enables retrying HTTP requests under certain failure conditions.

### Response
**Promise<Webhook>**

### Errors
- `errors.SDKError` (4XX, 5XX) - */*

### Example Usage
```typescript
import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await shippo.webhooks.getWebhook("<id>");

  console.log(result);
}

run();
```
```

--------------------------------

### SDK Initialization and Basic Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Demonstrates how to initialize the Shippo SDK with an API key and perform a basic operation, such as listing addresses.

```APIDOC
## SDK Initialization and Basic Usage

### Description
Initialize the Shippo SDK with your API key and demonstrate a basic API call.

### Method
```typescript
new Shippo({ apiKeyHeader: "<YOUR_API_KEY_HERE>" })
```

### Endpoint
N/A (SDK method)

### Parameters
#### Constructor Parameters
- **apiKeyHeader** (string) - Required - Your Shippo API token.
- **shippoApiVersion** (string) - Optional - The API version to use.

### Request Example
```typescript
import { Shippo } from "shippo";

const shippo = new Shippo({
    apiKeyHeader: "<YOUR_API_KEY_HERE>",
    // shippoApiVersion: "<YYYY-MM-DD>",
});

async function run() {
    const result = await shippo.addresses.list();
    console.log(result);
}

run();
```

### Response
#### Success Response (200)
- **result** (object) - The response from the addresses.list() call.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Copy .env.template to .env

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/examples/README.md

Before running examples, copy the template environment file and edit it with your actual credentials.

```bash
cp .env.template .env
```

--------------------------------

### UpdateCarrierAccountRequest Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/updatecarrieraccountrequest.md

An example of how to define an UpdateCarrierAccountRequest object in TypeScript.

```APIDOC
## UpdateCarrierAccountRequest

### Description
Represents the request body for updating a carrier account.

### Fields

#### Required Fields

- **carrierAccountId** (string): Object ID of the carrier account.

#### Optional Fields

- **carrierAccountBase** (object): Base object for carrier account details. Refer to [CarrierAccountBase](../../models/components/carrieraccountbase.md) for more information.
```

--------------------------------

### ServiceGroupUpdateRequest Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/servicegroupupdaterequest.md

An example of how to construct a ServiceGroupUpdateRequest object in TypeScript.

```APIDOC
## ServiceGroupUpdateRequest

### Description
Represents the request body for updating a service group.

### Usage
```typescript
import { ServiceGroupUpdateRequest } from "shippo/models/components";

let value: ServiceGroupUpdateRequest = {
  description: "USPS shipping options",
  flatRate: "5",
  flatRateCurrency: "USD",
  freeShippingThresholdCurrency: "USD",
  freeShippingThresholdMin: "5",
  name: "USPS Shipping",
  rateAdjustment: 15,
  type: "FLAT_RATE",
  objectId: "80feb1633d4a43c898f005850",
  isActive: true,
  serviceLevels: [],
};
```

### Fields
- **description** (string) - Optional - A description for the service group.
- **flatRate** (string) - Optional - The flat rate amount for the service group.
- **flatRateCurrency** (string) - Optional - The currency of the flat rate.
- **freeShippingThresholdCurrency** (string) - Optional - The currency for the free shipping threshold.
- **freeShippingThresholdMin** (string) - Optional - The minimum amount for free shipping.
- **name** (string) - Optional - The name of the service group.
- **rateAdjustment** (number) - Optional - A rate adjustment value.
- **type** (string) - Optional - The type of the service group (e.g., "FLAT_RATE").
- **objectId** (string) - Optional - The unique identifier for the service group.
- **isActive** (boolean) - Optional - Indicates if the service group is active.
- **serviceLevels** (array) - Optional - A list of service levels associated with the group.
```

--------------------------------

### CustomsDeclarationCreateRequest Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/customsdeclarationcreaterequest.md

An example of how to instantiate and populate the CustomsDeclarationCreateRequest object.

```APIDOC
## CustomsDeclarationCreateRequest

### Description
Represents the request object for creating a customs declaration.

### Properties
- **b13aFilingOption** (string) - Required - The option for filing the B13A.
- **certify** (boolean) - Required - Indicates if the declaration is certified.
- **certifySigner** (string) - Required - The name of the person certifying the declaration.
- **contentsExplanation** (string) - Required - A brief explanation of the contents.
- **dutiesPayor** (object) - Optional - Information about the duties payor.
  - **account** (string) - Required - The account number of the duties payor.
  - **type** (string) - Required - The type of duties payor (e.g., "THIRD_PARTY").
  - **address** (object) - Required - The address of the duties payor.
    - **name** (string) - Required - The name of the contact person.
    - **zip** (string) - Required - The zip code of the address.
    - **country** (string) - Required - The country of the address.
- **exporterIdentification** (object) - Optional - Identification details of the exporter.
  - **eoriNumber** (string) - Required - The EORI number of the exporter.
  - **taxId** (object) - Optional - Tax identification details.
    - **number** (string) - Required - The tax ID number.
    - **type** (string) - Required - The type of tax ID (e.g., "EIN").
- **invoice** (string) - Optional - The invoice number associated with the declaration.
- **metadata** (string) - Optional - Any metadata to associate with the declaration.
- **addressImporter** (object) - Required - The importer's address details.
  - **name** (string) - Required - The name of the importer.
  - **company** (string) - Optional - The company name of the importer.
  - **street1** (string) - Required - The first line of the street address.
  - **street3** (string) - Optional - The third line of the street address.
  - **streetNo** (string) - Optional - The street number.
  - **city** (string) - Required - The city of the importer.
  - **state** (string) - Optional - The state or province of the importer.
  - **zip** (string) - Required - The zip or postal code of the importer.
  - **country** (string) - Required - The country of the importer.
  - **phone** (string) - Optional - The phone number of the importer.
  - **email** (string) - Optional - The email address of the importer.
  - **isResidential** (boolean) - Optional - Indicates if the importer's address is residential.
- **contentsType** (string) - Required - The type of contents (e.g., "MERCHANDISE").
- **eelPfc** (string) - Optional - The Electronic Export Information (EEI) or Prioritize Foreign Country (PFC) code.
- **incoterm** (string) - Optional - The Incoterm for the shipment.
- **items** (array) - Required - An array of items included in the customs declaration.
- **nonDeliveryOption** (string) - Optional - The option for handling non-delivery (e.g., "RETURN").
- **test** (boolean) - Optional - Indicates if this is a test declaration.

### Example Usage
```typescript
import { CustomsDeclarationCreateRequest } from "shippo/models/components";

let value: CustomsDeclarationCreateRequest = {
  b13aFilingOption: "FILED_ELECTRONICALLY",
  certify: true,
  certifySigner: "Shawn Ippotle",
  contentsExplanation: "T-Shirt purchase",
  dutiesPayor: {
    account: "2323434543",
    type: "THIRD_PARTY",
    address: {
      name: "Patrick Kavanagh",
      zip: "80331",
      country: "DE",
    },
  },
  exporterIdentification: {
    eoriNumber: "PL123456790ABCDE",
    taxId: {
      number: "123456789",
      type: "EIN",
    },
  },
  invoice: "#123123",
  metadata: "Order ID #123123",
  addressImporter: {
    name: "Shwan Ippotle",
    company: "Shippo",
    street1: "Blumenstraße",
    street3: "",
    streetNo: "22",
    city: "München",
    state: "CA",
    zip: "80331",
    country: "DE",
    phone: "80331",
    email: "shippotle@shippo.com",
    isResidential: true,
  },
  contentsType: "MERCHANDISE",
  eelPfc: "NOEEI_30_37_a",
  incoterm: "DDP",
  items: [],
  nonDeliveryOption: "RETURN",
  test: true,
};
```
```

--------------------------------

### Initialize ObjectInfo

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/objectinfo.md

Demonstrates how to import and initialize an ObjectInfo object. Ensure the 'shippo/models/components' module is available in your project.

```typescript
import { ObjectInfo } from "shippo/models/components";

let value: ObjectInfo = {};
```

--------------------------------

### WebhookPayloadBatch Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/webhookpayload.md

Example of an empty components.WebhookPayloadBatch object. This payload is used for batch-related webhook events.

```typescript
const value: components.WebhookPayloadBatch = {};
```

```typescript
const value: components.WebhookPayloadBatch = {};
```

--------------------------------

### WebhookPayloadTrack Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/webhookpayload.md

Example of a components.WebhookPayloadTrack object. This payload contains detailed tracking information for a shipment.

```typescript
const value: components.WebhookPayloadTrack = {
  data: {
    addressFrom: {
      city: "Las Vegas",
      country: "US",
      state: "NV",
      zip: "89101",
    },
    addressTo: {
      city: "Las Vegas",
      country: "US",
      state: "NV",
      zip: "89101",
    },
    carrier: "usps",
    messages: [],
    metadata: "Order 000123",
    originalEta: new Date("2021-07-23T00:00:00Z"),
    servicelevel: {
      name: "Priority Mail Express",
      token: "usps_priority_express",
      parentServicelevel: {
        name: "Priority Mail Express",
        token: "usps_priority_express",
      },
    },
    trackingHistory: [],
    trackingNumber: "9205590164917312751089",
    trackingStatus: {
      location: {
        city: "Las Vegas",
        country: "US",
        state: "NV",
        zip: "89101",
      },
      objectCreated: new Date("2026-12-27T04:28:22.995Z"),
      objectId: "<id>",
      objectUpdated: new Date("2024-10-08T23:37:11.797Z"),
      status: "DELIVERED",
      substatus: {
        code: "information_received",
        text: "Information about the package received.",
        actionRequired: true,
      },
      statusDate: new Date("2016-07-23T00:00:00Z"),
      statusDetails:
        "Your shipment has been delivered at the destination mailbox.",
    },
  },
};
```

--------------------------------

### SDK Initialization

Source: https://context7.com/goshippo/shippo-javascript-sdk/llms.txt

Instantiate the Shippo client with your API key; optionally pin the API version.

```APIDOC
## SDK Initialization

Instantiate the `Shippo` client with your API key; optionally pin the API version.

```typescript
import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "shippo_test_595d9cb0c0e14497bf07e75ecfec6c6d",
  // Pin API version (optional, normally not required)
  shippoApiVersion: "2018-02-08",
});
```
```

--------------------------------

### InitiateOauth2SigninGlobals Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/initiateoauth2signinglobals.md

Demonstrates how to import and initialize the InitiateOauth2SigninGlobals model with an optional Shippo API version.

```typescript
import { InitiateOauth2SigninGlobals } from "shippo/models/operations";

let value: InitiateOauth2SigninGlobals = {
  shippoApiVersion: "2018-02-08",
};
```

--------------------------------

### CreateCustomsDeclarationGlobals Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/createcustomsdeclarationglobals.md

Demonstrates how to import and initialize the CreateCustomsDeclarationGlobals object with a specific API version.

```typescript
import { CreateCustomsDeclarationGlobals } from "shippo/models/operations";

let value: CreateCustomsDeclarationGlobals = {
  shippoApiVersion: "2018-02-08",
};
```

--------------------------------

### InitiateOauth2SigninRequest Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/initiateoauth2signinrequest.md

Demonstrates how to import and instantiate the InitiateOauth2SigninRequest object with required fields. Ensure you replace placeholder values with actual IDs and URIs.

```typescript
import { InitiateOauth2SigninRequest } from "shippo/models/operations";

let value: InitiateOauth2SigninRequest = {
  carrierAccountObjectId: "<id>",
  redirectUri: "https://pushy-godfather.name/",
};
```

--------------------------------

### WebhookPaginatedList Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/webhookpaginatedlist.md

An example demonstrating how to use the WebhookPaginatedList model in TypeScript, including its fields like next, previous, and results.

```APIDOC
## WebhookPaginatedList

### Description
Represents a paginated list of webhooks.

### Fields

| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| `next` | *string* | :heavy_minus_sign: | N/A | baseurl?page=3&results=10 |
| `previous` | *string* | :heavy_minus_sign: | N/A | baseurl?page=1&results=10 |
| `count` | *number* | :heavy_minus_sign: | N/A | |
| `results` | [components.Webhook](../../models/components/webhook.md)[] | :heavy_minus_sign: | N/A | |

### Example Usage

```typescript
import { WebhookPaginatedList } from "shippo/models/components";

let value: WebhookPaginatedList = {
  next: "baseurl?page=3&results=10",
  previous: "baseurl?page=1&results=10",
  results: [
    {
      event: "track_updated",
      url: "https://example.com/shippo-webhook",
      active: true,
      isTest: false,
    },
  ],
};
```
```

--------------------------------

### Initialize Shippo SDK and List Addresses

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/README.md

Initialize the Shippo SDK with your API key and fetch a list of addresses. Ensure your API key is correctly formatted and kept secure.

```typescript
import { Shippo } from "shippo";

const shippo = new Shippo({
    apiKeyHeader: "<YOUR_API_KEY_HERE>",
    // the API version can be globally set, though this is normally not required
    // shippoApiVersion: "<YYYY-MM-DD>",
});

async function run() {
    const result = await shippo.addresses.list();

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

run();

```

--------------------------------

### CoreRate Object Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/transactionrate.md

Example of a `components.CoreRate` object, which includes detailed pricing and service information. This is used when a label is purchased.

```typescript
const value: components.CoreRate = {
  amount: "5.5",
  amountLocal: "5.5",
  currency: "USD",
  currencyLocal: "USD",
  objectId: "adcfdddf8ec64b84ad22772bce3ea37a",
  provider: "USPS",
  carrierAccount: "078870331023437cb917f5187429b093",
  servicelevelName: "Priority Mail",
  servicelevelToken: "fedex_ground",
};
```

--------------------------------

### AddShipmentsToBatchRequest Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/operations/addshipmentstobatchrequest.md

This example demonstrates how to construct an AddShipmentsToBatchRequest object in TypeScript, including specifying the batch ID and an array of shipments to be added.

```APIDOC
## AddShipmentsToBatchRequest

### Description
Represents a request to add shipments to a batch.

### Fields

#### `batchId`
- **Type**: `string`
- **Required**: Yes
- **Description**: Object ID of the batch.

#### `requestBody`
- **Type**: `Array<BatchShipmentCreateRequest>`
- **Required**: Yes
- **Description**: Array of shipments to add to the batch.

### Example Usage

```typescript
import { AddShipmentsToBatchRequest } from "shippo/models/operations";

let value: AddShipmentsToBatchRequest = {
  batchId: "<id>",
  requestBody: [
    {
      carrierAccount: "a4391cd4ab974f478f55dc08b5c8e3b3",
      metadata: "SHIPMENT #1",
      servicelevelToken: "fedex_ground",
      shipment: {
        extra: {
          accountsReceivableCustomerAccount: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          appropriationNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          billOfLadingNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          cod: {
            amount: "5.5",
            currency: "USD",
            paymentMethod: "CASH",
          },
          codNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          customerReference: {
            refSort: 1,
          },
          dealerOrderNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          deptNumber: {
            refSort: 3,
          },
          fdaProductCode: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          insurance: {
            amount: "5.5",
            currency: "USD",
          },
          invoiceNumber: {
            refSort: 2,
          },
          manifestNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          modelNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          partNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          poNumber: {
            refSort: 2,
          },
          productionCode: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          purchaseRequestNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          rmaNumber: {
            refSort: 1,
          },
          salespersonNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          serialNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          storeNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
          transactionReferenceNumber: {
            prefix: "ABC",
            value: "value",
            refSort: 1,
          },
        },
        metadata: "Customer ID 123456",
        shipmentDate: "2021-03-22T12:00:00Z",
        addressFrom: "d799c2679e644279b59fe661ac8fa488",
        addressReturn: "d799c2679e644279b59fe661ac8fa488",
        addressTo: "d799c2679e644279b59fe661ac8fa489",
        customsDeclaration: "adcfdddf8ec64b84ad22772bce3ea37a",
        carrierAccounts: [
          "065a4a8c10d24a34ab932163a1b87f52",
          "73f706f4bdb94b54a337563840ce52b0",
        ],
        parcels: [
          "<value>",
        ],
      },
    },
  ],
};
```
```

--------------------------------

### Initialize Security Model with API Key Header

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/security.md

Demonstrates how to import and initialize the Security model, setting the API key header. This is useful for configuring authentication with the Shippo API.

```typescript
import { Security } from "shippo/models/components";

let value: Security = {
  apiKeyHeader: "<value>",
};
```

--------------------------------

### List Addresses with Shippo SDK

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/USAGE.md

Initialize the Shippo SDK and list all addresses. Ensure you replace '<YOUR_API_KEY_HERE>' with your actual Shippo API key.

```typescript
import { Shippo } from "shippo";

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

async function run() {
  const result = await shippo.addresses.list();

  console.log(result);
}

run();

```

--------------------------------

### WebhookPayloadTransaction Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/webhookpayload.md

Example of a components.WebhookPayloadTransaction object. This payload contains details about a completed transaction, including label information and tracking data.

```typescript
const value: components.WebhookPayloadTransaction = {
  data: {
    createdBy: {
      firstName: "Shwan",
      lastName: "Ippotle",
      username: "shippotle@shippo.com",
    },
    labelFileType: "PDF_4x6",
    labelUrl:
      "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.",
      },
    ],
    objectId: "915d94940ea54c3a80cbfa328722f5a1",
    objectOwner: "shippotle@shippo.com",
    parcel: "e94c7fdfdc7b495dbb390a28d929d90a",
    qrCodeUrl:
      "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    rate: "ec9f0d3adc9441449c85d315f0997fd5",
    status: "SUCCESS",
    trackingNumber: "9499907123456123456781",
    trackingStatus: "DELIVERED",
    trackingUrlProvider:
      "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
  },
};
```

```typescript
const value: components.WebhookPayloadTransaction = {
  data: {
    createdBy: {
      firstName: "Shwan",
      lastName: "Ippotle",
      username: "shippotle@shippo.com",
    },
    labelFileType: "PDF_4x6",
    labelUrl:
      "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.",
      },
    ],
    objectId: "915d94940ea54c3a80cbfa328722f5a1",
    objectOwner: "shippotle@shippo.com",
    parcel: "e94c7fdfdc7b495dbb390a28d929d90a",
    qrCodeUrl:
      "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    rate: "ec9f0d3adc9441449c85d315f0997fd5",
    status: "SUCCESS",
    trackingNumber: "9499907123456123456781",
    trackingStatus: "DELIVERED",
    trackingUrlProvider:
      "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
  },
};
```

--------------------------------

### Get Carrier Parcel Template

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/sdks/carrierparceltemplates/README.md

Retrieves a specific carrier parcel template by its token. This allows you to get details about a pre-defined parcel template from a carrier.

```APIDOC
## Get Carrier Parcel Template

### Description
Retrieves a specific carrier parcel template by its token.

### Method
GET

### Endpoint
/carrier-parcel-templates/{carrierParcelTemplateToken}

### Parameters
#### Path Parameters
- **carrierParcelTemplateToken** (string) - Required - The unique string representation of the carrier parcel template.

#### Query Parameters
- **options** (object) - Optional - Used to set various options for making HTTP requests.
  - **fetchOptions** (object) - Optional - 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.
  - **retries** (object) - Optional - Enables retrying HTTP requests under certain failure conditions.

### Response
#### Success Response (200)
- **Promise** (object) - A promise that resolves to a CarrierParcelTemplate object.

### Errors
- **errors.SDKError** (4XX, 5XX) - An error occurred during the request.
```

--------------------------------

### Initialize Shippo Client

Source: https://context7.com/goshippo/shippo-javascript-sdk/llms.txt

Instantiate the Shippo client with your API key. Optionally pin the API version.

```typescript
import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "shippo_test_595d9cb0c0e14497bf07e75ecfec6c6d",
  // Pin API version (optional, normally not required)
  shippoApiVersion: "2018-02-08",
});
```

--------------------------------

### ShippoAccountPaginatedList Example Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/shippoaccountpaginatedlist.md

Demonstrates how to import and use the ShippoAccountPaginatedList type in TypeScript. This example shows the structure of a paginated list with next, previous, and results fields.

```typescript
import { ShippoAccountPaginatedList } from "shippo/models/components";

let value: ShippoAccountPaginatedList = {
  next: "baseurl?page=3&results=10",
  previous: "baseurl?page=1&results=10",
  results: [
    {
      email: "hippo@shippo.com",
      firstName: "Shippo",
      lastName: "Meister",
      companyName: "Acme",
      objectId: "adcfdddf8ec64b84ad22772bce3ea37a",
    },
  ],
};
```

--------------------------------

### AddressValidationResults Example Usage

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/addressvalidationresults.md

Demonstrates how to import and use the AddressValidationResults type in TypeScript. This example shows initializing an AddressValidationResults object with validation status and a warning message.

```typescript
import { AddressValidationResults } from "shippo/models/components";

let value: AddressValidationResults = {
  isValid: false,
  messages: [
    {
      code: "Unknown Street",
      source: "Shippo Address Validator",
      text:
        "City, State and ZIP Code are valid, but street address is not a match.",
      type: "address_warning",
    },
  ],
};
```

--------------------------------

### String Rate ID Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/transactionrate.md

Example of a `TransactionRate` represented as a simple string ID. This is typically used when the rate is older than 7 days or for simplified transaction objects.

```typescript
const value: string = "ec9f0d3adc9441449c85d315f0997fd5";
```

--------------------------------

### TrackingStatus Model Example

Source: https://github.com/goshippo/shippo-javascript-sdk/blob/main/docs/models/components/trackingstatus.md

Demonstrates how to define a TrackingStatus object with detailed tracking information. Ensure the 'shippo/models/components' module is imported.

```typescript
import { TrackingStatus } from "shippo/models/components";

let value: TrackingStatus = {
  location: {
    city: "Las Vegas",
    country: "US",
    state: "NV",
    zip: "89101",
  },
  objectCreated: new Date("2025-04-06T07:22:19.251Z"),
  objectId: "<id>",
  objectUpdated: new Date("2025-11-09T01:10:59.062Z"),
  status: "DELIVERED",
  substatus: {
    code: "information_received",
    text: "Information about the package received.",
    actionRequired: true,
  },
  statusDate: new Date("2016-07-23T00:00:00Z"),
  statusDetails: "Your shipment has been delivered at the destination mailbox.",
};
```