### Shipping Options Response Example

Source: https://github.com/usps/api-examples/blob/main/README.md

Example JSON response detailing available shipping options, including commitment times, prices, and rate details for a given package.

```json
{
    "originZIPCode": "05485-8016",
    "destinationZIPCode": "38746-0230",
    "pricingOptions": [
        {
            "shippingOptions": [
                {
                    "mailClass": "PARCEL_SELECT",
                    "rateOptions": [
                        {
                            "commitment": {
                                "name": "3 Days",
                                "scheduleDeliveryDate": "2024-05-04"
                            },
                            "totalPrice": 3.40,
                            "totalBasePrice": 3.40,
                            "rates": [
                                {
                                    "description": "Parcel Select Nonmachinable DDU Single-piece",
                                    "startDate": "2024-01-21",
                                    "endDate": "",
                                    "price": 3.4,
                                    "zone": "00",
                                    "weight": 1.0,
                                    "dimensionalWeight": 0.0,
                                    "fees": [],
                                    "SKU": "DVXP0XXUXC00010"
                                }
                            ],
                            "extraServices": [
                                {
                                    "name": "Global Direct Entry",
                                    "price": 0.00,
                                    "SKU": "NA"
                                }
                            ]
                        },
                        {
                            "commitment": {
                                "name": "3 Days",
                                "scheduleDeliveryDate": "2024-05-04"
                            },
                            "totalPrice": 5.48,
                            "totalBasePrice": 5.48,
                            "rates": [
                                {
                                    "description": "Parcel Select Nonmachinable DNDC Single-piece",
                                    "startDate": "2024-01-21",
                                    "endDate": "",
                                    "price": 5.48,
                                    "zone": "00",
                                    "weight": 1.0,
                                    "dimensionalWeight": 0.0,
                                    "fees": [],
                                    "SKU": "DVXP0XXCXC00010"
                                }
                            ],
                            "extraServices": [
                                {
                                    "name": "Global Direct Entry",
                                    "price": 0.00,
                                    "SKU": "NA"
                                }
                            ]
                        },
                        {
                            "commitment": {
                                "name": "3 Days",
                                "scheduleDeliveryDate": "2024-05-04"
                            },
                            "totalPrice": 5.29,
                            "totalBasePrice": 5.29,
                            "rates": [
                                {
                                    "description": "Parcel Select Nonmachinable DSCF SCF",
                                    "startDate": "2024-01-21",
                                    "endDate": "",
                                    "price": 5.29,
                                    "zone": "00",
                                    "weight": 1.0,
                                    "dimensionalWeight": 0.0,
                                    "fees": [],
                                    "SKU": "DVXP0XXFXC00010"
                                }
                            ],
                            "extraServices": [
                                {
                                    "name": "Global Direct Entry",
                                    "price": 0.00,
                                    "SKU": "NA"
                                }
                            ]
                        }
                    ],
                    "extraServices": [
                        {
                            "name": "Global Direct Entry",
                            "price": 0.00,
                            "SKU": "NA"
                        }
                    ]
                }
            ]
        }
    ]
}
```

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

### Domestic Prices Response Example

Source: https://github.com/usps/api-examples/blob/main/README.md

This is an example of the JSON response received when requesting domestic prices. It details various rate options, including base prices, total prices, and associated extra services.

```json
{
    "rateOptions": [
        {
            "totalBasePrice": 4.59,
            "totalPrice": 5.84,
            "rates": [
                {
                    "description": "Parcel Select Machinable DDU Single-piece",
                    "priceType": "COMMERCIAL",
                    "price": 4.59,
                    "weight": 7.0,
                    "dimWeight": 0.0,
                    "fees": [],
                    "startDate": "2023-07-09",
                    "endDate": "",
                    "mailClass": "PARCEL_SELECT",
                    "zone": "00",
                    "SKU": "DVXP0XXUXC00070"
                }
            ],
            "extraServices": [
                {
                    "extraService": "415",
                    "name": "Label Delivery",
                    "priceType": "COMMERCIAL",
                    "price": 1.25,
                    "warnings": [],
                    "SKU": "DXQX0XXXXCX0000"
                }
            ]
        },
        {
            "totalBasePrice": 7.86,
            "totalPrice": 9.11,
            "rates": [
                {
                    "description": "Parcel Select Machinable DNDC Single-piece",
                    "priceType": "COMMERCIAL",
                    "price": 7.86,
                    "weight": 7.0,
                    "dimWeight": 0.0,
                    "fees": [],
                    "startDate": "2023-07-09",
                    "endDate": "",
                    "mailClass": "PARCEL_SELECT",
                    "zone": "00",
                    "SKU": "DVXP0XXCXC00070"
                }
            ],
            "extraServices": [
                {
                    "extraService": "415",
                    "name": "Label Delivery",
                    "priceType": "COMMERCIAL",
                    "price": 1.25,
                    "warnings": [],
                    "SKU": "DXQX0XXXXCX0000"
                }
            ]
        },
        {
            "totalBasePrice": 6.79,
            "totalPrice": 8.04,
            "rates": [
                {
                    "description": "Parcel Select Machinable DSCF SCF",
                    "priceType": "COMMERCIAL",
                    "price": 6.79,
                    "weight": 7.0,
                    "dimWeight": 0.0,
                    "fees": [],
                    "startDate": "2023-07-09",
                    "endDate": "",
                    "mailClass": "PARCEL_SELECT",
                    "zone": "00",
                    "SKU": "DVXP0XXFTC00070"
                }
            ],
            "extraServices": [
                {
                    "extraService": "415",
                    "name": "Label Delivery",
                    "priceType": "COMMERCIAL",
                    "price": 1.25,
                    "warnings": [],
                    "SKU": "DXQX0XXXXCX0000"
                }
            ]
        },
        {
            "totalBasePrice": 5.74,
            "totalPrice": 6.99,
            "rates": [
                {
                    "description": "Parcel Select Machinable Single-piece",
                    "priceType": "COMMERCIAL",
                    "price": 5.74,
                    "weight": 7.0,
                    "dimWeight": 0.0,
                    "fees": [],
                    "startDate": "2023-07-09",
                    "endDate": "",
                    "mailClass": "PARCEL_SELECT",
                    "zone": "00",
                    "SKU": "DVXP0XXBXC00070"
                }
            ],
            "extraServices": [
                {
                    "extraService": "415",
                    "name": "Label Delivery",
                    "priceType": "COMMERCIAL",
                    "price": 1.25,
                    "warnings": [],
                    "SKU": "DXQX0XXXXCX0000"
                }
            ]
        }
    ]
}
```

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

### Create a Container Label

Source: https://github.com/usps/api-examples/blob/main/README.md

Allows the caller to get a container label and associate packages to that container.

```APIDOC
## POST /containers/v3/containers

### Description
Allows the caller to get a container label and associate packages to that container.

### Method
POST

### Endpoint
https://apis.usps.com/containers/v3/containers

### Parameters
#### Request Body
- **imageInfo** (object) - Required - Information about the image and label type.
  - **imageType** (string) - Required - Type of image (e.g., PDF).
  - **labelType** (string) - Required - Type of label (e.g., 6X4LABEL).
- **trackingNumbers** (array of strings) - Required - List of tracking numbers to associate.
- **sortType** (string) - Required - Type of sort (e.g., SACK).
- **destinationEntryFacilityType** (string) - Required - Type of destination entry facility.
- **destinationZIPCode** (string) - Required - Destination ZIP code.
- **mailClass** (string) - Required - Mail class (e.g., PARCEL_SELECT).
- **originAddress** (object) - Required - Origin address details.
  - **streetAddress** (string) - Required.
  - **secondaryAddress** (string) - Optional.
  - **city** (string) - Required.
  - **state** (string) - Required.
  - **ZIPCode** (string) - Required.
  - **ZIPPlus4** (string) - Required.
  - **urbanization** (string) - Optional.
- **mailerName** (string) - Required - Name of the mailer.
- **processingCategory** (string) - Required - Processing category (e.g., MACHINABLE).
- **containerTopology** (string) - Required - Topology of the container (e.g., NESTED).
- **MID** (string) - Required - Mailer Identification number.

### Request Example
```json
{
    "imageInfo": {
        "imageType": "PDF",
        "labelType": "6X4LABEL"
    },
	"trackingNumbers":[
        "9261212345678900017634"
    ],
    "sortType": "SACK",
    "destinationEntryFacilityType": "DESTINATION_DELIVERY_UNIT",
    "destinationZIPCode": "06701",
    "mailClass": "PARCEL_SELECT",
    "originAddress": {
        "streetAddress": "900 BRENTWOOD RD NE",
        "secondaryAddress": "",
        "city": "Washington",
        "state": "DC",
        "ZIPCode": "20018",
        "ZIPPlus4": "0000",
        "urbanization": ""
    },
    "mailerName": "John Smith AC.",
    "processingCategory": "MACHINABLE",
    "containerTopology": "NESTED",
    "MID": "XXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **containerID** (string) - The ID of the created container.
- **sortType** (string) - The sort type used.
- **destinationEntryFacilityType** (string) - The destination entry facility type.
- **destinationZIPCode** (string) - The destination ZIP code.
- **mailClass** (string) - The mail class.
- **originAddress** (object) - The origin address details.
- **mailerName** (string) - The mailer name.
- **processingCategory** (string) - The processing category.
- **containerTopology** (string) - The container topology.
- **warnings** (array) - Any warnings generated during the process.
- **MID** (string) - The Mailer Identification number.

#### Response Example
```json
{
    "containerID": "99M900066875EMA000052",
    "sortType": "SACK",
    "destinationEntryFacilityType": "DESTINATION_DELIVERY_UNIT",
    "destinationZIPCode": "06701",
    "mailClass": "PARCEL_SELECT",
    "originAddress": {
        "streetAddress": "900 BRENTWOOD RD NE",
        "secondaryAddress": "",
        "city": "Washington",
        "state": "DC",
        "urbanization": "",
        "ZIPCode": "20018",
        "ZIPPlus4": "0000"
    },
    "mailerName": "John Smith AC.",
    "processingCategory": "MACHINABLE",
    "containerTopology": "NESTED",
    "warnings": [],
    "MID": "XXXXXXXXX"
}
```
```

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

### Get Comprehensive Package Shipping Options

Source: https://context7.com/usps/api-examples/llms.txt

Returns a complete list of all available rates, service standards, and shipping options for a package.

```APIDOC
## POST https://apis.usps.com/shipments/v3/options/search

### Description
Returns a complete list of all available rates, service standards, and shipping options for a package in a single request, across all eligible mail classes and destination entry combinations.

### Method
POST

### Endpoint
https://apis.usps.com/shipments/v3/options/search

### Request Body
- **pricingOptions** (array) - Required - Pricing options for the shipment.
  - **priceType** (string) - Required - Type of price (e.g., "COMMERCIAL").
  - **paymentAccount** (object) - Required - Payment account details.
    - **accountType** (string) - Required - Type of account (e.g., "EPS").
    - **accountNumber** (string) - Required - The account number.
- **originZIPCode** (string) - Required - The origin ZIP code.
- **destinationZIPCode** (string) - Required - The destination ZIP code.
- **packageDescription** (object) - Required - Description of the package.
  - **weight** (number) - Required - The weight of the package.
  - **length** (number) - Required - The length of the package.
  - **height** (number) - Required - The height of the package.
  - **width** (number) - Required - The width of the package.
  - **mailClass** (string) - Required - The mail class (e.g., "PARCEL_SELECT").
  - **extraServices** (array) - Optional - Array of extra service codes.
  - **mailingDate** (string) - Required - The mailing date in YYYY-MM-DD format.
  - **packageValue** (number) - Optional - The declared value of the package.

### Request Example
```json
{
  "pricingOptions": [{
    "priceType": "COMMERCIAL",
    "paymentAccount": { "accountType": "EPS", "accountNumber": "1234567890" }
  }],
  "originZIPCode": "05485",
  "destinationZIPCode": "38746",
  "packageDescription": {
    "weight": 1,
    "length": 12,
    "height": 8,
    "width": 6,
    "mailClass": "PARCEL_SELECT",
    "extraServices": [365],
    "mailingDate": "2024-05-01",
    "packageValue": 35
  }
}
```

### Response
#### Success Response (200)
- **pricingOptions** (array) - Pricing options with available shipping options.
  - **priceType** (string) - Type of price.
  - **shippingOptions** (array) - Available shipping options.
    - **mailClass** (string) - The mail class.
    - **rateOptions** (array) - Rate options for the mail class.
      - **commitment** (object) - Commitment details.
        - **name** (string) - Name of the commitment (e.g., "3 Days").
        - **scheduleDeliveryDate** (string) - Scheduled delivery date.
      - **totalPrice** (number) - The total price for the shipping option.
      - **rates** (array) - Detailed rates.
        - **description** (string) - Description of the rate.
        - **price** (number) - The price for this rate component.
        - **zone** (string) - The shipping zone.

#### Response Example
```json
{
  "pricingOptions": [{
    "priceType": "COMMERCIAL",
    "shippingOptions": [{
      "mailClass": "PARCEL_SELECT",
      "rateOptions": [
        {
          "commitment": { "name": "3 Days", "scheduleDeliveryDate": "2024-05-04" },
          "totalPrice": 3.40,
          "rates": [{ "description": "Parcel Select Nonmachinable DDU Single-piece", "price": 3.40, "zone": "00" }]
        }
      ]
    }]
  }]
}
```
```

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

### OAuth Refresh Token Request

Source: https://github.com/usps/api-examples/blob/main/README.md

Example of how to request a new access token using a refresh token.

```APIDOC
## POST /oauth2/v3/token

### Description
Requests a new access token using a valid refresh token.

### Method
POST

### Endpoint
https://apis.usps.com/oauth2/v3/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **grant_type** (string) - Required - Must be set to "refresh_token".
- **refresh_token** (string) - Required - The refresh token obtained previously.

### Request Example
```json
{
	"client_id": "{{CLIENT_ID}}",
	"client_secret": "{{CLIENT_SECRET}}",
	"grant_type": "refresh_token",
	"refresh_token": "XXXXXXXXXXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The new access token.
- **token_type** (string) - The type of token, usually "Bearer".
- **issued_at** (string) - The timestamp when the token was issued.
- **expires_in** (string) - The time in seconds until the token expires.
- **status** (string) - The status of the token request.
- **scope** (string) - The granted scopes for the token.
- **issuer** (string) - The issuer of the token.
- **refresh_token** (string) - The new refresh token (if applicable).
- **refresh_token_issued_at** (string) - The timestamp when the refresh token was issued.
- **refresh_token_status** (string) - The status of the refresh token.
- **refresh_token_expires_in** (string) - The time in seconds until the refresh token expires.
- **refresh_count** (string) - The number of times the refresh token has been used.
- **client_id** (string) - The client ID associated with the token.
- **application_name** (string) - The name of the application.
- **api_products** (string) - The API products associated with the token.
- **public_key** (string) - The public key for token verification.

### Response Example
```json
{
    "access_token": "XXXXXXXXXXXXXXXXX",
    "token_type": "Bearer",
    "issued_at": "1111111111111",
    "expires_in": "11111",
    "status": "approved",
    "scope": "prices labels tracking",
    "issuer": "api.usps.com",
    "refresh_token": "XXXXXXXXXXXXXXXXX",
    "refresh_token_issued_at": 1111111111111,
    "refresh_token_status": "approved",
    "refresh_token_expires_in": 11111,
    "refresh_count": 1,
    "client_id": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
    "application_name": "XXXXXX-XXXX-XXXX-XXX-XXXXXXXXXXXX",
    "api_products": "[XXXXXXX]",
    "public_key": "XXXXXXXXXXXXXXXXX"
}
```
```

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

### Get Shipping Options - POST Request

Source: https://github.com/usps/api-examples/blob/main/README.md

Use this endpoint to generate a list of shipping options that comply with USPS Shipping Standards. Requires authentication and detailed package information.

```sh
curl	-X 'POST' 'https://apis.usps.com/shipments/v3/options/search' \
	--header 'Accept: application/json' \
	--header 'Authorization: Bearer $TOKEN' \
	--data '{
		"pricingOptions": [
			{
				"priceType": "COMMERCIAL",
				"paymentAccount": {
					"accountType": "EPS",
					"accountNumber": "XXXXXXXXXX"
				}
			}
		],
		"originZIPCode": "05485-8016",
		"destinationZIPCode": "38746 0230",
		"packageDescription": {
			"weight": 1,
			"length": 1,
			"height": 1,
			"width": 1,
			"girth": 1,
			"mailClass": "PARCEL_SELECT",
			"extraServices": [
				365
			],
			"mailingDate": "2024-05-01",
			"packageValue": 35
		}
	}'
```

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

### Obtain OAuth Access Token (Client Credentials)

Source: https://context7.com/usps/api-examples/llms.txt

Use this to get an access token for API calls when acting as the client application. Tokens expire and must be refreshed.

```sh
# Step 1: Get access token
curl -X 'POST' 'https://apis.usps.com/oauth2/v3/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

# Response:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiJ9...",
#   "token_type": "Bearer",
#   "issued_at": "1684972800000",
#   "expires_in": "3599",
#   "status": "approved",
#   "scope": "addresses service-delivery-standards locations prices tracking labels"
# }

# Step 2: Store token for use in subsequent requests
export TOKEN="eyJhbGciOiJSUzI1NiJ9..."
```

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

### Create a Container Label - POST Request

Source: https://github.com/usps/api-examples/blob/main/README.md

Use this endpoint to create a container label and associate packages with it. Ensure you have a valid Bearer token for authorization.

```sh
curl -X 'POST' 'https://apis.usps.com/containers/v3/containers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{ \
    "imageInfo": { \
        "imageType": "PDF", \
        "labelType": "6X4LABEL" \
    }, \
	"trackingNumbers":[ \
        "9261212345678900017634" \
    ], \
    "sortType": "SACK", \
    "destinationEntryFacilityType": "DESTINATION_DELIVERY_UNIT", \
    "destinationZIPCode": "06701", \
    "mailClass": "PARCEL_SELECT", \
    "originAddress": { \
        "streetAddress": "900 BRENTWOOD RD NE", \
        "secondaryAddress": "", \
        "city": "Washington", \
        "state": "DC", \
        "ZIPCode": "20018", \
        "ZIPPlus4": "0000", \
        "urbanization": "" \
    }, \
    "mailerName": "John Smith AC.", \
    "processingCategory": "MACHINABLE", \
    "containerTopology": "NESTED", \
    "MID": "XXXXXXXXX" \
}' 
```

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

### USPS Label Edit Response Example

Source: https://github.com/usps/api-examples/blob/main/README.md

This is an example of a successful response when editing a USPS label. It includes details about the label's address, tracking number, postage cost, and commitment.

```json
{
    "labelAddress": {
        "streetAddress": "1100 WYOMING ST",
        "secondaryAddress": "STE 150",
        "city": "SAINT LOUIS",
        "state": "MO",
        "ZIPCode": "63118",
        "ZIPPlus4": "2628",
        "firstName": "JOE",
        "lastName": "DOE",
        "ignoreBadAddress": false
    },
    "routingInformation": "123456789102",
    "trackingNumber": "{{trackingNumber}}",
    "postage": 7.05,
    "extraServices": [
        {
            "name": "USPS Tracking",
            "price": 0.0,
            "SKU": "XXXXXXXXXXXXX"
        }
    ],
    "zone": "01",
    "commitment": {
        "name": "6 Days",
        "scheduleDeliveryDate": "2024-06-22"
    },
    "weightUOM": "LB",
    "weight": 1.0,
    "fees": [],
    "labelBrokerID": "",
    "constructCode": "C01",
    "SKU": "XXXXXXXXXXXXX"
}
```

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

### International Prices - Base Rates List Request

Source: https://github.com/usps/api-examples/blob/main/README.md

This example demonstrates how to request a list of base rates for international shipping, including details like mail class, price type, SKU, and description.

```APIDOC
## International Prices - Base Rates List Request

### Description
Retrieves a list of base rates for international shipping services.

### Method
POST

### Endpoint
/shipping/v1/international-rates

### Request Body
```json
{
    "startDate": "2024-01-21",
    "endDate": "",
    "SKU": "IPXX0XXXXB01040",
    "price": 50.6,
    "weight": 4,
    "description": "Priority Mail International Machinable ISC Single-piece"
}
```

### Response
#### Success Response (200)
```json
{
    "rates": [
        {
            "mailClass": "PRIORITY_MAIL_INTERNATIONAL",
            "priceType": "COMMERCIAL_BASE",
            "dimWeight": 0,
            "zone": "01",
            "fees": [],
            "startDate": "2024-01-21",
            "endDate": "",
            "SKU": "IPXX0XXXXB01040",
            "price": 50.6,
            "weight": 4,
            "description": "Priority Mail International Machinable ISC Single-piece"
        }
    ],
    "totalBasePrice": 50.6
}
```
```

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

### Revoke OAuth Token Request

Source: https://github.com/usps/api-examples/blob/main/README.md

Example of how to revoke an existing OAuth token.

```APIDOC
## POST /oauth2/v3/revoke

### Description
Revokes an existing OAuth token, invalidating it for future use.

### Method
POST

### Endpoint
https://apis.usps.com/oauth2/v3/revoke

### Parameters
#### Request Body
- **token** (string) - Required - The token to revoke.
- **token_type_hint** (string) - Optional - A hint about the type of token (e.g., "access_token" or "refresh_token").

### Request Example
```json
{
	"token": "ExDTmpomcDt6pTbFVvSgQ1km39YmX8Oy",
	"token_type_hint": "refresh_token"
}
```

### Response
#### Success Response (200)
Indicates the token was successfully revoked.
```

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

### Prepare OAuth Credentials

Source: https://github.com/usps/api-examples/blob/main/README.md

Prepare your OAuth credentials for use in API requests. Ensure you have a valid client ID, client secret, customer registration ID, and mailer ID.

```sh
CLIENT_ID=XXXX
CLIENT_SECRET=XXXX
CUSTOMER_REGISTRATION_ID=XXXX
MAILER_ID=XXXX
```

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

### International Prices - Base Rates List Request

Source: https://github.com/usps/api-examples/blob/main/README.md

Given size/weight/destination of pieces, returns a list of potential rates. Can also search for contract rates by providing mailer id, EPS, permit number or vendor number and account. If searching for contract rates, then a specified mail class is required.

```APIDOC
## POST https://apis.usps.com/international-prices/v3/base-rates-list/search

### Description
Retrieves a list of potential international shipping rates based on package details and destination. This endpoint can also be used to search for contract rates by providing account information.

### Method
POST

### Endpoint
https://apis.usps.com/international-prices/v3/base-rates-list/search

### Parameters
#### Request Body
- **originZIPCode** (string) - Required - The origin ZIP code for the shipment.
- **foreignPostalCode** (string) - Required - The destination postal code.
- **destinationCountryCode** (string) - Required - The destination country code (e.g., 'CA' for Canada).
- **weight** (number) - Required - The weight of the package in pounds.
- **mailingDate** (string) - Required - The date of mailing in 'YYYY-MM-DD' format.
- **length** (number) - Optional - The length of the package in inches.
- **width** (number) - Optional - The width of the package in inches.
- **height** (number) - Optional - The height of the package in inches.
- **mailClass** (string) - Required - The mail class for the shipment (e.g., 'PRIORITY_MAIL_INTERNATIONAL').
- **accountType** (string) - Optional - The type of account for contract rates (e.g., 'EPS').
- **accountNumber** (string) - Optional - The account number for contract rates.

### Request Example
```json
{
  "originZIPCode": "22407",
  "foreignPostalCode": "10109",
  "destinationCountryCode": "CA",
  "weight": 4,
  "mailingDate": "2024-02-29",
  "length": 6,
  "width": 0.25,
  "height": 3,
  "mailClass": "PRIORITY_MAIL_INTERNATIONAL",
  "accountType": "EPS",
  "accountNumber": "XXXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **rateOptions** (array) - A list of available rate options.
  - **rates** (array) - A list of specific rates within an option.
    - **mailClass** (string) - The mail class for this rate.
    - **priceType** (string) - The type of pricing (e.g., 'COMMERCIAL_BASE').
    - **dimWeight** (number) - Dimensional weight.
    - **zone** (string) - The shipping zone.
    - **fees** (array) - Any associated fees.
    - **startDate** (string) - The start date for the rate.
    - **endDate** (string) - The end date for the rate.
    - **SKU** (string) - The Stock Keeping Unit for the rate.
    - **price** (number) - The price of the rate.
    - **weight** (number) - The weight associated with this rate.
    - **description** (string) - A description of the rate.
  - **totalBasePrice** (number) - The total base price for this rate option.

#### Response Example
```json
{
    "rateOptions": [
        {
            "rates": [
                {
                    "mailClass": "PRIORITY_MAIL_INTERNATIONAL",
                    "priceType": "COMMERCIAL_BASE",
                    "dimWeight": 0,
                    "zone": "01",
                    "fees": [],
                    "startDate": "2024-01-21",
                    "endDate": "",
                    "SKU": "IPFE0XXXXB01040",
                    "price": 29.66,
                    "weight": 4,
                    "description": "Priority Mail International ISC Flat Rate Envelope"
                }
            ],
            "totalBasePrice": 29.66
        }
    ]
}
```
```

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

### Get Tracking Summary

Source: https://context7.com/usps/api-examples/llms.txt

Returns a concise delivery status message for a single USPS package by tracking number.

```APIDOC
## GET https://apis.usps.com/tracking/v3/tracking/{trackingNumber}?expand=summary

### Description
Returns a concise delivery status message for a single USPS package by tracking number.

### Method
GET

### Endpoint
https://apis.usps.com/tracking/v3/tracking/{trackingNumber}?expand=summary

### Parameters
#### Path Parameters
- **trackingNumber** (string) - Required - The tracking number of the package.

### Response
#### Success Response (200)
- **TrackResults** (object) - Contains tracking information.
  - **TrackInfo** (object) - Specific tracking details.
    - **@ID** (string) - The tracking number.
    - **TrackSummary** (string) - A summary of the tracking status.

#### Response Example
```json
{
  "TrackResults": {
    "TrackInfo": {
      "@ID": "9400111899223083553030",
      "TrackSummary": "USPS is now in possession of your item as of 7:31 am on February 15, 2023 in RICHMOND, VA 23227."
    }
  }
}
```
```

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

### City and State Lookup Response

Source: https://github.com/usps/api-examples/blob/main/README.md

Example response for a city and state lookup based on a ZIP code. It returns the corresponding city and state.

```json
{
    "city": "ALPHARETTA",
    "state": "GA"
} 

```

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

### Handle Expired Token in Shell Script

Source: https://context7.com/usps/api-examples/llms.txt

This script demonstrates how to obtain an access token, make an API request, and handle potential expired token scenarios (HTTP 401). Ensure you have `jq` installed for JSON parsing.

```shell
TOKEN=$(curl -s -X POST 'https://apis.usps.com/oauth2/v3/token' \
  --header 'Content-Type: application/json' \
  --data "{\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\",\"grant_type\":\"client_credentials\"}" \
  | jq -r '.access_token')

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -X GET "https://apis.usps.com/tracking/v3/tracking/$TRACKING_NUMBER?expand=DETAIL" \
  --header "Authorization: Bearer $TOKEN")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -1)

if [ "$HTTP_CODE" -eq 200 ]; then
  echo "Tracking data: $BODY"
elif [ "$HTTP_CODE" -eq 401 ]; then
  echo "Token expired — re-authenticate and retry"
else
  echo "API error $HTTP_CODE: $BODY"
fi
```

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

### Address Validation Response

Source: https://github.com/usps/api-examples/blob/main/README.md

Example response from the Address API after validation and standardization. It includes the standardized address components and additional delivery information.

```json
{
    "firm": null,
    "address": {
        "streetAddress": "3120 M ST NW",
        "streetAddressAbbreviation": null,
        "secondaryAddress": null,
        "city": "WASHINGTON",
        "cityAbbreviation": null,
        "state": "DC",
        "postalCode": null,
        "province": null,
        "ZIPCode": "20007",
        "ZIPPlus4": "3704",
        "urbanization": null,
        "country": null,
        "countryISOCode": null
    },
    "additionalInfo": {
        "deliveryPoint": "20",
        "carrierRoute": "C036",
        "DPVConfirmation": "Y",
        "DPVCMRA": "N",
        "business": "Y",
        "centralDeliveryPoint": "N",
        "vacant": "N"
    },
    "corrections": [
		{
			"code": "",
			"text": ""
		}
	],
	"matches": [
		{
			"code": "31",
			"text": "Single Response - exact match"
		}
	]
}
```

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

### ZIP Code Lookup Response

Source: https://github.com/usps/api-examples/blob/main/README.md

Example response from the ZIP Code lookup API. It provides the standardized address including the ZIP Code and ZIP+4.

```json
{
    "firm": null,
    "address": {
        "streetAddress": "1273 PALE SAN VITORES RD",
        "streetAddressAbbreviation": null,
        "secondaryAddress": null,
        "city": "TAMUNING",
        "cityAbbreviation": null,
        "state": "GU",
        "postalCode": null,
        "province": null,
        "ZIPCode": "96913",
        "ZIPPlus4": "4208",
        "urbanization": null,
        "country": null,
        "countryISOCode": null
    }
}
```

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

### Get Service Standards

Source: https://github.com/usps/api-examples/blob/main/README.md

Retrieve the average delivery days for a selected mail class between origin and destination ZIP codes. An authorization token is required.

```sh
curl	-X 'GET' 'https://apis.usps.com/service-standards/v3/standards?originZIPCode=10018&destinationZIPCode=95823&mailClass=PRIORITY_MAIL&destinationType=HOLD_FOR_PICKUP&serviceTypeCodes=925' \
		--header 'Authorization: Bearer $TOKEN' \

```

```json
[
    {
        "mailClass": "PRIORITY_MAIL",
        "originZIPCode": 10018,
        "destinationZIPCode": 95823,
        "days": 2,
        "effectiveAcceptanceDate": "2023-05-23",
        "scheduledDeliveryDate": "2023-05-25"
    }
]
```

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

### Look Up City and State by ZIP Code

Source: https://context7.com/usps/api-examples/llms.txt

Retrieves the city and state associated with a given ZIP code. Requires a valid ZIP code.

```sh
curl -X 'GET' \
  'https://apis.usps.com/addresses/v3/city-state?ZIPCode=30022' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer $TOKEN'

# Response:
# { "city": "ALPHARETTA", "state": "GA" }
```

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

### Add Packages to Existing Container (Shell)

Source: https://context7.com/usps/api-examples/llms.txt

Adds tracking numbers to an existing container using its ID. Requires a bearer token and a JSON payload with tracking numbers.

```shell
curl -X 'POST' \
  'https://apis.usps.com/containers/v3/containers/99M900066875EMA000051/packages' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $TOKEN' \
  --data '{ 
    "trackingNumbers": ["9261212345678900017627"]
  }'
```

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

### Carrier Pickup - Get

Source: https://github.com/usps/api-examples/blob/main/README.md

Retrieves a previously scheduled carrier pickup using its confirmation number. The response includes the ETag for updating or cancelling the pickup.

```APIDOC
## GET /carrier-pickup/{Confirmation Number}

### Description
Get the previously scheduled carrier pickup by confirmation number. Responds with the entity tag (ETag) to use when updating or cancelling this pickup.

### Method
GET

### Endpoint
/carrier-pickup/{Confirmation Number}

### Parameters
#### Path Parameters
- **Confirmation Number** (string) - Required - The confirmation number of the pickup.

### Request Example
```sh
curl -X 'GET' 'https://apis.usps.com/pickup/v3/carrier-pickup/{Confirmation Number}' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer $TOKEN'
```

### Response
#### Success Response (200)
- **confirmationNumber** (string) - The confirmation number of the pickup.
- **pickupAddress** (object) - Details of the pickup address.
- **packages** (array) - Information about the packages for pickup.
- **estimatedWeight** (string) - The estimated weight of the packages.
- **pickupLocation** (object) - Details about the pickup location.
- **pickupDate** (string) - The date of the pickup.

#### Response Example
```json
{
    "confirmationNumber": "{Confirmation Number}",
    "pickupAddress": {
        "firstName": "JOHN",
        "lastName": "SMITH",
        "firm": "FIRM",
        "address": {
            "streetAddress": "4120 BINGHAM AVE",
            "secondaryAddress": null,
            "city": "SAINT LOUIS",
            "state": "MO",
            "ZIPCode": "63116",
            "ZIPPlus4": "2520",
            "urbanization": null
        },
        "contact": [
            {
                "email": "JOHN.SMITH@FIRM.COM"
            },
            {
                "phone": "3333333333",
                "extension": null
            }
        ]
    },
    "packages": [
        {
            "packageType": "FIRST-CLASS_PACKAGE_SERVICE",
            "packageCount": "1"
        },
        {
            "packageType": "PRIORITY_MAIL_EXPRESS",
            "packageCount": "0"
        },
        {
            "packageType": "PRIORITY_MAIL",
            "packageCount": "0"
        },
        {
            "packageType": "RETURNS",
            "packageCount": "0"
        },
        {
            "packageType": "INTERNATIONAL",
            "packageCount": "0"
        },
        {
            "packageType": "OTHER",
            "packageCount": "0"
        }
    ],
    "estimatedWeight": "5",
    "pickupLocation": {
        "packageLocation": "OFFICE",
        "specialInstructions": "HAVE A NICE DAY"
    },
    "pickupDate": "2023-04-20"
}
```
```

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

### Get Service Standards (Average Days)

Source: https://context7.com/usps/api-examples/llms.txt

Retrieves the average number of days for a service standard between two ZIP codes for a given mail class.

```APIDOC
## GET /service-standards/v3/standards

### Description
Returns the average number of days for a service standard between two ZIP codes for a given mail class.

### Method
GET

### Endpoint
https://apis.usps.com/service-standards/v3/standards

### Parameters
#### Query Parameters
- **originZIPCode** (string) - Required - The origin ZIP code.
- **destinationZIPCode** (string) - Required - The destination ZIP code.
- **mailClass** (string) - Required - The mail class.
- **destinationType** (string) - Required - The type of destination.
- **serviceTypeCodes** (string) - Required - The service type codes.

### Request Example
```sh
curl -X 'GET' \
  'https://apis.usps.com/service-standards/v3/standards?originZIPCode=10018&destinationZIPCode=95823&mailClass=PRIORITY_MAIL&destinationType=HOLD_FOR_PICKUP&serviceTypeCodes=925' \
  --header 'Authorization: Bearer $TOKEN'
```

### Response
#### Success Response (200)
- **mailClass** (string) - The mail class.
- **originZIPCode** (string) - The origin ZIP code.
- **destinationZIPCode** (string) - The destination ZIP code.
- **days** (number) - The average number of days for the service standard.
- **effectiveAcceptanceDate** (string) - The effective acceptance date.
- **scheduledDeliveryDate** (string) - The scheduled delivery date.

#### Response Example
```json
[
  {
    "mailClass": "PRIORITY_MAIL",
    "originZIPCode": 10018,
    "destinationZIPCode": 95823,
    "days": 2,
    "effectiveAcceptanceDate": "2023-05-23",
    "scheduledDeliveryDate": "2023-05-25"
  }
]
```
```