Best Practices

The following are recommended best practices. If you encounter a problem with the APIs, please see Troubleshooting.

Developer Accounts

Use a distribution list as the email address for the developer account

The email address used to sign up for a Pitney Bowes developer account cannot be changed. Therefore, when signing up for a developer account, use a distribution list that is monitored by multiple people. Do not use an email address that is specific to one person.

Important

Do not use an open, public mailbox, such as Mailinator.

Third-party integrators should not own developer accounts

If you are a third-party integrator contracting to create custom API integrations for individual clients, then the client must be the owner of the Pitney Bowes developer account.

This does not apply if you are part of an organization that provides a shipping software platform as part of a product offering. If your organization provides a shipping software platform as a product offering, you are encouraged to create a developer account with Pitney Bowes.

Note

This applies specifically to third-party integrators who are contracting to create custom API integrations for individual clients. This does not apply to organizations that provide a shipping platform as part of a product offering.

API Calls

Integrate to both PB Expedited and PB Delivery and PB Returns

When integrating to the Pitney Bowes Carrier Service, integrate to both PB Expedited and the PB Delivery and PB Returns, to provide shippers a range of options and provide the opportunity to redistribute volume during peak periods. Configure API calls for Expedited Delivery, PB Delivery, Expedited Returns, and PB Returns. For details, see the Pitney Bowes Expedited and PB Delivery and PB Return Services page.

Use an OAuth token for its full 10 hours

Once generated, the OAuth token is valid for 10 hours. Reuse the token for its full 10 hours to reduce the number of API calls your application makes. Do not recreate the OAuth token for every transaction.

Validate addresses prior to shipping

Run the Address Validation API during upstream operations, such as during order entry. If an address fails, run the Suggest Addresses API to get the correct address before printing the label.

Do not pass fields without values

When issuing an API request, do not pass empty fields and do not pass NULL values. In your request, pass only those fields for which there is a value to be entered. If an optional parameter has no value, exclude the parameter from the request. Do not pass the parameter as empty or NULL.

Call the APIs from your web servers

Call the APIs from your web servers. Do not call the APIs from your clients’ browsers. Do not call the APIs from client-side applications.

Testing and Optimization

Test on Sandbox before deploying to Production

To see how your application will run on production, test it first on the Sandbox environment. Sandbox uses the same hardware and code as the Production environment and is intended specifically to show you how your application will run on Production.

Contact Support before running performance or load tests

If you plan to run performance or load tests, first contact the Client Support team at ClientSupportTechServices@pb.com with the dates and times, to avoid your tests being blacklisted.

Note

Do not run performance or load tests without first contacting Support.

Optimize parameters if you use multithreading

The Global Ecommerce APIs are designed to support both single and multithreaded applications. If you use multithreading, optimize the following on Sandbox before deploying to Production:

  • Number of threads

  • Number of sockets per process

  • Memory

  • Multithreading vs. Multiprocessing

Important

Response times for multithreaded calls on Sandbox might differ from response times for multithreaded calls on Production. Sandbox is not configured as a performance environment.

Contact us if you will regularly exceed 100 TPS for label operations

If you will use multithreading or high-volume batch processing for printing labels, please note that Pitney Bowes has safeguards in place to make sure that runaway applications and other high-volume activities don’t jeopardize the platform for other users. As a result, before deploying any high-volume processes that might regularly exceed 100 TPS for label-printing operations, please contact the Client Support team at ClientSupportTechServices@pb.com so we can work with you to optimize your throughput on the platform.

Network

Keep the connection open during periods of high volume

If you print multiple labels in a short period of time, leave the connection to Pitney Bowes open instead of opening it separately for each label request.

Configure your network with failover options

As with any network application, prepare for network and server failures by configuring your network to automatically transfer workload to secondary components should the primary components become unavailable.

Security/Certificates

  • Ensure applications (browsers, mobile apps, APIs) use the latest TLS versions.

  • Clients should validate server certificates during the handshake process and ensure that the certificate is issued by a trusted Certificate Authority (CA).

  • Track expiration and revocation status for root and/or intermediate certificates.

  • Keep your Trust Store updated with the necessary root certificates of the major Certificate Authorities.

  • Always use HTTPS for known domains with HSTS enabled.