Shippo Getting Started: Account Setup & First API Call (2026)

Getting started overview

Integrating with the Shippo API enables developers to programmatically manage shipping operations, including rate comparison, label generation, and tracking. This guide provides a focused walkthrough to get you from account creation to your first successful API request. The process involves setting up a Shippo account, obtaining API keys, and executing a basic API call using either a direct HTTP request or one of Shippo's official SDKs.

Shippo's API is RESTful, utilizing predictable resource-oriented URLs and standard HTTP response codes. Data is typically exchanged in JSON format. Developers can interact with the API directly or leverage the provided client libraries for various programming languages, which simplify common tasks like authentication and request formatting. For a comprehensive overview of all available endpoints and data models, consult the Shippo API reference documentation.

This guide specifically covers:

• Account creation and API key retrieval.
• Environment setup for API calls.
• Constructing and executing your first API request to create a shipping label.

Create an account and get keys

Before making any API calls, you must create a Shippo account and obtain your API keys. These keys authenticate your requests and link them to your account.

1. Sign up for a Shippo account

Navigate to the Shippo pricing page and choose a plan. A free plan is available, which includes per-label fees, making it suitable for initial development and testing. Complete the registration process by providing the required information.

2. Access your API keys

Once your account is active, log in to the Shippo dashboard. API keys are managed in the "API" section of your settings. Shippo provides two distinct types of API keys:

• Test API Key: Used for development and testing purposes. Requests made with this key do not incur charges or create live shipping labels.
• Live API Key: Used for production environments. Requests made with this key are live, incur charges, and generate actual shipping labels.

For getting started, you will primarily use the Test API Key. Locate and copy this key; it typically starts with shippo_test_.... Keep your API keys secure and never expose them in client-side code or public repositories. For best practices in API key management, refer to general security guidelines for API key security best practices.

Your first request

This section walks through making a basic API call to create a shipping label. We'll use the Python SDK for demonstration, but the principles apply to other SDKs and direct HTTP requests.

Prerequisites

• Python 3 installed.
• Shippo Python SDK installed: pip install shippo
• Your Test API Key.

Step-by-step: Create a label

The process of creating a shipping label involves several steps:

1. Define sender and recipient addresses.
2. Specify the parcel details.
3. Create a shipment object combining addresses and parcel.
4. Generate rates for the shipment.
5. Select a rate and purchase a label.

1. Initialize the Shippo client

import shippo

# Replace with your actual Test API Key
shippo.config.api_key = "YOUR_SHIPPO_TEST_API_KEY"

2. Define addresses

You need a "from" address (sender) and a "to" address (recipient).

from_address = shippo.Address.create(
    name="Shippo Team",
    street1="228 Park Ave S",
    street2="Suite 200",
    city="New York",
    state="NY",
    zip="10003",
    country="US",
    phone="+1 212 555 1212",
    email="[email protected]"
)

to_address = shippo.Address.create(
    name="Shippo User",
    street1="123 Main Street",
    city="San Francisco",
    state="CA",
    zip="94107",
    country="US",
    phone="+1 415 555 1212",
    email="[email protected]"
)

3. Define parcel

Specify the dimensions and weight of the package.

parcel = shippo.Parcel.create(
    length="5",
    width="5",
    height="5",
    distance_unit="in",
    weight="2",
    mass_unit="lb"
)

4. Create a shipment

Combine the addresses and parcel into a shipment object. You also specify the carrier accounts you want rates from (e.g., "shippo_usps" for a Shippo-provided USPS account).

shipment = shippo.Shipment.create(
    address_from=from_address.object_id,
    address_to=to_address.object_id,
    parcels=[parcel.object_id],
    carrier_accounts=["shippo_usps"], # Use 'shippo_usps' for testing with Shippo's default USPS account
    async=False
)

# The shipment object will contain available rates
if shipment.rates:
    print(f"Shipment created with {len(shipment.rates)} rates.")
else:
    print("No rates found for this shipment.")

5. Purchase a label

Select the desired rate from the shipment.rates array and purchase the label. The first rate is often chosen for simplicity in testing.

if shipment.rates:
    # Select the first rate for demonstration
    rate = shipment.rates[0]

    # Purchase the label
    label = shippo.Transaction.create(
        rate=rate.object_id,
        label_file_type="PDF_4x6"
    )

    if label.status == "SUCCESS":
        print("Label created successfully!")
        print(f"Label URL: {label.label_url}")
        print(f"Tracking Number: {label.tracking_number}")
    else:
        print(f"Failed to create label: {label.messages}")
else:
    print("Cannot purchase label without rates.")

This sequence creates a complete shipping label. In a real application, you would store the label.label_url to print the label and label.tracking_number for tracking purposes.

Summary of First Request Steps

Here's a quick reference for the steps involved in making your first Shippo API call:

Common next steps

After successfully creating your first label, consider these common next steps to further integrate Shippo into your application:

• Webhooks: Implement webhooks to receive real-time updates on tracking events, label status changes, and more. This reduces the need for constant polling and ensures your application has the most current information. Refer to the Shippo webhooks documentation for setup instructions.
• Advanced Rating: Explore more complex rating scenarios, such as requesting rates from specific carrier accounts, applying discounts, or using different service levels.
• Batch Label Creation: For high-volume shipping, learn how to create labels in batches to optimize performance and reduce API calls.
• Error Handling: Implement robust error handling in your application to gracefully manage API failures, invalid requests, and other potential issues.
• Go Live: Once testing is complete, switch to your Live API Key and configure your production environment. Remember that live API calls incur charges.
• Tracking: Integrate Shippo's tracking capabilities to provide customers with real-time updates on their package delivery status.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Key: Ensure you are using the correct API key (Test key for testing, Live key for production) and that it is correctly set in your environment or SDK configuration. A common mistake is using a Live key in a test environment or vice-versa.
• Verify Request Body: Double-check the JSON structure and data types of your request payload. Even minor typos or incorrect values can lead to validation errors. Use the Shippo API reference to confirm required fields and acceptable formats.
• Examine Error Messages: Shippo's API provides detailed error messages in its responses. Read them carefully, as they often pinpoint the exact issue (e.g., "Invalid address", "Missing required parameter").
• Review Carrier Accounts: If you are not seeing rates, ensure that the carrier_accounts array in your shipment creation request includes valid carrier account IDs that are active in your Shippo account. For testing, using shippo_usps is a good starting point.
• SDK vs. Direct HTTP: If using an SDK, ensure it's up to date. If making direct HTTP requests, verify your headers (especially Authorization and Content-Type).
• Consult Documentation: The Shippo documentation portal is an extensive resource. Search for specific error codes or endpoint details.
• Shippo Dashboard Logs: Check the API logs within your Shippo dashboard. These logs can provide insights into the requests your application is sending and the responses it's receiving, which can be invaluable for debugging.