Ecommerce APIs Overview¶
Introduction¶
The Pitney Bowes Global Ecommerce APIs let you integrate Pitney Bowes Ecommerce services into your platform. The APIs follow the principles of the REST architectural style and use HTTP as the underlying protocol. All requests use HTTPS. Responses include success or failure messages and any requested resources. Resource objects use JSON formatting.
The Ecommerce APIs comprise the following:
Shipping APIs: Resources for full-featured shipping integration with multiple carriers. To enroll merchants with the Shipping APIs use the Merchant Accounts APIs.
Merchant Accounts APIs: Resources for adding and managing the shippers who use the Shipping APIs.
Fulfillment APIs: Resources for integration with PB Fulfillment™ Services.
This page describes the components of the Ecommerce APIs. To get quickly started with the APIs after reading this Overview, see Getting Started.
Developer Account¶
To use the Ecommerce 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. To 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 use the Production environment, Developer Hub gives you access to your postage balances and payment options. For questions on developer accounts, see the Developer Account FAQs or contact Pitney Bowes at ShippingAPIBusinessDevelopment@pb.com.
To upgrade to the Production environment, contact Pitney Bowes at ShippingAPIBusinessDevelopment@pb.com.
Note
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.
Merchants¶
When you print a shipping label through the 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 as described in Manage Merchant Accounts. Each merchant enrolled in your developer account has a unique Shipper ID. You reference the ID when requesting transactions on the merchant’s behalf.
To print labels for your real-life shippers, you must add them as merchants in your developer account. The Ecommerce APIs support two models for adding merchants and handling their postage payments. Both are described in Manage Merchant Accounts.
Carriers¶
When you add a merchant to your developer account, the merchant has access to print USPS® labels through PB Expedited and USPS PMOD. The APIs integrate with other carriers as well, and once a merchant enrolls with your developer account, you can add other carriers to the merchant’s account. For available carriers and onboarding instructions, see Carriers.
API Environments¶
The APIs have separate Sandbox and Production environments, which are described below. Each environment has its own set of base URLs, which are the common prefixes for groups of API operations in the environment. The following shows the Production environment’s Rates API call with the base URL underlined:
Sandbox Environment¶
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.
Note
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.
Sandbox Base URLs¶
https://shipping-api-sandbox.pitneybowes.com/shippingservices/*
https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/*
https://shipping-api-sandbox.pitneybowes.com/*
Production Environment¶
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 Base URLs¶
https://shipping-api.pitneybowes.com/shippingservices/*
https://shipping-api.pitneybowes.com/shippingservices/fulfillment/*
https://shipping-api.pitneybowes.com/*
Comparison of the Environments¶
For a comparison, see What are the differences between Sandbox and Production?
PB Postage Accounts¶
When you upgrade to a Production developer account, 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 Manage Merchant Accounts. For FAQs on PB Postage Accounts, see Payments FAQs.
HTTPS Requirement¶
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.
TLS¶
The minimum supported security protocol for connection to the 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.
Authentication¶
Each request to the 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 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.
API Resources¶
For lists of the API resources, see the following:
Versions¶
Each request URL includes the API’s version number. For example, v2 in the following API call:
POST /v2/developers/{developerId}/merchants/registration
API Responses¶
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.
Errors¶
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, include the 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.
API Status¶
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
Support¶
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 Shipping FAQs and Accounts FAQs.
APAC Services¶
For PB Services requests that originate in the Asia-Pacific Region, Pitney Bowes provides APAC Services to optimize performance. See Asia-Pacific (APAC) Services for PB Delivery.
Client SDKs¶
See Client SDKs.