The Pitney Bowes Complete Shipping APIs let you integrate Pitney Bowes and other carrier services into your platform. The APIs provide a unified set of resources for all supported carriers. The APIs follow the principles of the REST architectural style and use HTTP as the underlying protocol. For security, requests use HTTPS. Responses include success or failure messages and any requested resources. Resource objects use JSON formatting.
This page describes access to the APIs and describes the API components. To get quickly started with the APIs after reading this Overview page, see Getting Started.
To use the PB Shipping APIs, you must have a Pitney Bowes developer account. You can create a free account and access the Sandbox test environment by going to Pitney Bowes Developer Hub Signup. To sign up, use a regularly monitored email, such as a distribution list. The email address you choose cannot be changed.
Once you create a developer account, you can begin testing the APIs on the Sandbox environment. You can use the default merchant that comes with your account or create additional merchants. For steps to create a developer account and begin testing the APIs, see the Getting Started page.
You can access your developer account at any time at Pitney Bowes Developer Hub. Developer Hub gives you access to your API keys, merchants, transaction history, and other information. If you upgrade to the Production environment, Developer Hub also gives you access to your postage balances and payment options.
To upgrade to the Production environment, you can contact Pitney Bowes at ShippingAPIBusinessDevelopment@pb.com.
If you are a third-party integrator, your client should own the developer account. For more information, see Third-party integrators should not own developer accounts on the Best Practices page.
When you print a label through the PB Shipping APIs, you do so on behalf of a merchant. Your developer account comes with a default merchant, and you can add multiple additional merchants. Each merchant enrolled in your developer account has a unique Shipper ID that you reference when requesting the merchant’s transactions. For information on adding merchants to your developer account, see Merchant Accounts.
To request transactions for your real-life shippers, you must add them as merchants in your developer account. Once you do, you can use the APIs to print labels and request transactions on their behalves.
When you add a merchant to your developer account, the merchant is given access to print USPS® labels through Pitney Bowes’s Expedited Services and through USPS PMOD. Merchants can also register to use these additional carriers and services.
The PB Shipping APIs provide the Sandbox and Production environments. Each environment has its own set of base URLs, as listed in the sections below. Note that the base URL is just one part of the API call:
The Sandbox environment is a free test environment that is intended for all your development and testing work prior to deployment on Production. Sandbox gives full access to all the API calls available on Production but prints only test labels. Sandbox does not use real money. Your Pitney Bowes developer account provides free access to the Sandbox environment.
Sandbox uses the following base URL: https://shipping-api-sandbox.pitneybowes.com/shippingservices/
The base URL is used for all API calls on Sandbox except Token Generation. For Token Generation, see Generate an OAuth Token.
The Sandbox environment has daily limits on the number of requests you can make per API resource. The limits differ per resource but accommodate daily testing and development. The limits do not accommodate load tests. If you exceed the daily limit for a resource, contact Client Support at ClientSupportTechServices@pb.com or +1(844) 470-6626 and ask that your limit be reset for the day.
To use the Production environment you must upgrade your developer account. Production uses real money and prints labels used for real shipments. Never use the Production environment for testing. Before you can upgrade to Production, you must add a payment method to your developer account. Note that you cannot use your existing Sandbox merchants in the Production environment but instead must add the merchants to Production separately.
Production uses the following base URL: https://shipping-api.pitneybowes.com/shippingservices/
The base URL is used for all API calls on Production except Token Generation. For Token Generation, see Generate an OAuth Token.
For more information on the environments, see What are the differences between Sandbox and Production?
PB Postage Accounts¶
When you upgrade a developer account from Sandbox to Production, you set up a PB Postage Account to pay shipping costs. Both developers and merchants can have PB Postage Accounts. A merchant will have a PB Postage Account if paying for postage directly, as described in Merchant Accounts. For FAQs on PB Postage Accounts, see Payments FAQs.
All API requests must use HTTPS. HTTPS uses Transport Layer Security (TLS) to verify the identity of the accessed API server and to encrypt communications.
The minimum supported security protocol for connection to the PB Shipping APIs is TLS v1.2.
To test whether your servers support TLS v1.2: From your servers, issue the following GET operation. The operation retrieves a resource that accepts only the TLS v1.2 protocol:
curl -X GET https://api-test.pitneybowes.com/tlstest
The following response confirms your servers support TLS v1.2:
200 OK TLS_Connection_Success
For help or questions, please contact Client Support at ClientSupportTechServices@pb.com.
Each request to the PB Shipping APIs requires authentication via an OAuth
token generated from the key and secret associated with your developer
account. You pass the OAuth token in the
Authorization header when making
an API call. To generate a token, invoke the Generate OAuth Token API using the key and secret for the environment to be
accessed (Sandbox or Production). Once generated, an OAuth token is reusable
for 10 hours.
HTTP Request Headers¶
All API requests require one or more HTTP headers. All requests require the
Authorization header, which authenticates the developer to the PB Shipping
APIs. Please see a request’s documentation page for the required headers for that request.
Important: Do not pass a header that you do not intend to use. Instead, omit the header.
Important: Do not pass a header with the NULL value.
Each request URL includes the API’s version number. For example,
v2 in the
following API call:
All API requests return an HTTP response that includes an HTTP status code, HTTP response headers, and, if applicable, a response body containing JSON-formatted data. The HTTP status code indicates the success or failure of the request. The request body, if present, contains either a resource object (returned by a successful request) or error information (if the request failed). If a request returns a large result set, the API spreads the result set over multiple pages. For requests that do this, the documentation for the API request gives details.
If an error occurs, the APIs return application-specific error information in
the response body. Pitney Bowes provides a standard structure for returned errors. To use the standard structure,
X-PB-UnifiedErrorStructure header set to
true with each API
request. For more information, see Error Object.
For a list of error codes and links to solutions, see Error Codes.
Pitney Bowes provides a status portal at https://apistatus.pitneybowes.com/. The status portal displays:
Up-to-date status of the APIs
Scheduled maintenance windows
Information on past incidents
This documentation provides a set of Best Practices to follow to avoid problems. If you do encounter an issue, please contact us for help resolving it. For answers to common questions, please see the FAQ pages.
For PB Standard requests that originate in the Asia-Pacific Region, Pitney Bowes provides APAC Services to optimize performance. See Asia-Pacific (APAC) Services for PB Standard Delivery.
Pitney Bowes provides the following client SDKs on GitHub. The SDKs support all the operations of the Shipping APIs, except the operations that govern merchant-account management. Pitney Bowes provides the following client SDKs:
In addition to the client SDKs, Pitney Bowes provides an OpenAPI definition you can use to generate an SDK in a language other than those provided above. See OpenAPI Definition.
Searching on Multiple Keywords in this Documentation¶
This documentation provides a Search box above the Table of Contents. Note that when you search on a multiple keywords, such as “PB Standard Returns,” the search will return pages that contain just some of the keywords as well as pages that contain all of them. If your search returns too many pages, please use the Glossary, which not only defines terms but also provides links to the most relevant pages.
To quickly find relevant pages for multi-word terms, please use the Glossary.