Getting Started with the Shipping APIs


Follow these steps to get started with the Sandbox test environment. Once testing is complete, transition to the Production environment by following the outlined steps. For an overview of the Pitney Bowes Shipping APIs, click here.

1. Sign up or log in on Sandbox Developer Hub

Start by signing up for a free Pitney Bowes developer account on the sandbox developer hub Signup page.

  • Fill out all the required details on the Registration form, including your Email Address, First Name, Last Name, Company Name, Phone Number, and other mandatory details.

  • Use a regularly monitored email, such as a distribution list, as this email address cannot be changed.

  • After successful registration, user will receive an email at the registered email address.

  • Complete your registration by using the verification link provided in the received email and setup a new password.

If you already have an account, log into your account at the sandbox developer hub login page.

2. Get your API key and secret

Your sandbox developer account comes with a sandbox key and secret that give you access to the APIs in the test environment. The key and secret are unique to your account.

  • Log in to your account.

  • Navigate to API Keys and copy your Sandbox key and secret.

3. Get your Developer ID

Your Developer ID is required by certain API calls.

  • In your developer account, in the upper right corner, click your name or company name and select Your Account.

  • Copy your Developer ID.

4. Get your default merchant’s Shipper ID

To get you started quickly, your sandbox developer account comes with a default merchant. You can use the default merchant for testing. As with all merchants, the default merchant is identified by its unique Shipper ID.

  • In your developer account, in the left pane navigation, click Onboarding Merchants.

  • Copy the Shipper ID for your default merchant.

5. Ensure your system meets the TLS requirement

The minimum supported security protocol for connection to the Pitney Bowes Shipping APIs is TLS v1.2. To test whether your environment supports TLS v1.2, issue the following GET operation:

curl -X GET https://api-test.pitneybowes.com/tlstest

A response of TLS_Connection_Success indicates your system meets the requirement.

6. Generate an OAuth token

To make a request to the Pitney Bowes Shipping APIs, you must have an OAuth token. The token identifies and authenticates the developer account making the request.

To generate a token, first encode your API key and secret in the following format using a Base64 encoder. Be sure to include the colon between the key and secret.

<API_key>:<API_secret>

Generate the OAuth token using the following API call, replacing <base64_value> with the Base64-encoded value:

curl -X POST https://shipping-api-sandbox.pitneybowes.com/oauth/token \
-H "Authorization: Basic <base64_value>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

The API returns an OAuth token in the access_token field, as shown in the example response below:

{
    "access_token": "mL3Ec6yp67uYGm0DnLiqPjux0AFY",
    "tokenType": "BearerToken",
    "issuedAt": "1498168771002",
    "expiresIn": "35999",
    "clientID": "a3cDEFghI1jK2LMnOP3qRstU4vWX5Yz",
    "org": "pitneybowes"
}

Note

The token is valid for 10 hours.

7. Test the APIs in Sandbox

Test the APIs using the Sandbox environment. Sandbox uses the following base URL:

  • Shipping APIs:
    https://shipping-api-sandbox.pitneybowes.com/shippingservices/*

    For the Shipping APIs, a good place to start is with the Create Shipment API. Try printing a Priority Mail label using PB Expedited as the carrier. Use your default merchant’s Shipper ID. See this example.

    Next, try printing a Parcel Select label using PB Delivery as the carrier. See this example.

    For details on carriers, see Carriers. For the sequence of operations to ship a parcel, see the Shipping Workflow.

Transition to Production

After testing the APIs in the Sandbox environment, follow these steps to move to Production:

1. Sign Up on the Production Developer Hub

Sign up for an account on the Production Developer Hub. This step ensures you have separate credentials for production use.

2. Upgrade to Production

To upgrade to a Production account, contact Pitney Bowes at ShippingAPIBusinessDevelopment@pb.com. Upon approval, you will receive access to your Production API keys and credentials.

3. Get Your Production Credentials

  • Log in on Production developer hub page.

  • Follow the same steps as for Sandbox to retrieve your API key, secret, Developer ID,default merchant’s Shipper ID and generate an OAuth token for the Production environment.

4. Use Production APIs

  • You are now ready to make requests to the Production environment.

  • Printing Your First Production Label: When printing your first production label, you must ensure your postage account has sufficient funds to cover the cost of the label. In case of insufficient funds, you might encounter an error while your account is being funded.