USPS API Examples

The Intelligent Mail Container barcode (IMcb) provides visibility at the mail aggregate level. It is used on mailer-generated pallet labels to uniquely identify containers such as pallets, All Purpose Containers, hampers, and pallet boxes. The IMcb serves two primary purposes:

1. It identifies the mail owner.
2. It provides a link between the electronic mailing record and the physical mail aggregate.

All USPS APIs require an OAuth 2.0 access token passed in the Authorization header using the Bearer token scheme.

To authenticate, you must first register your application in the USPS Developer Portal to obtain a CLIENT_ID and CLIENT_SECRET. Additionally, you will need a valid Customer Registration ID (CUSTOMER_REGISTRATION_ID) and Mailer ID (MAILER_ID) from your USPS Business Customer Gateway Business System Administrator (BSA).

Required credentials for setup:

• CLIENT_ID
• CLIENT_SECRET
• CUSTOMER_REGISTRATION_ID
• MAILER_ID

Use the authorization_code grant type to obtain an access token and a refresh_token by providing an authorization code obtained from the user.

Endpoint: POST https://apis.usps.com/oauth2/v3/token

curl -X 'POST' 'https://apis.usps.com/oauth2/v3/token' \
     --header 'Content-Type: application/json' \
     --data '{
		"client_id": "{{CLIENT_ID}}",
		"client_secret": "{{CLIENT_SECRET}}",
		"code": "{{CODE}}",
		"redirect_uri": "https://mycompany.com/authorize",
		"scope": "prices labels tracking",
		"state": "nonce=abscdefg#",
		"grant_type": "authorization_code"
		}'

When an access token expires, use the refresh_token grant type to obtain a new access token without requiring user re-authentication.

Endpoint: POST https://apis.usps.com/oauth2/v3/token

curl -X 'POST' 'https://apis.usps.com/oauth2/v3/token' \
     --header 'Content-Type: application/json' \
     --data '{
		"client_id": "{{CLIENT_ID}}",
		"client_secret": "{{CLIENT_SECRET}}",
		"grant_type": "refresh_token",
		"refresh_token": "XXXXXXXXXXXXXXXXX"
		}'

Use this endpoint to invalidate an existing token.

Endpoint: POST https://apis.usps.com/oauth2/v3/revoke

curl -X 'POST' 'https://apis.usps.com/oauth2/v3/revoke' \
	--header 'Content-Type: application/json' \
	--header 'Authorization: Bearer $TOKEN' \
	--data '{
		"token": "ExDTmpomcDt6pTbFVvSgQ1km39YmX8Oy",
		"token_type_hint": "refresh_token"
		}'

The client_credentials grant type is the primary OAuth flow supported by USPS. Use this to obtain an access token by providing your client credentials.

Endpoint: POST https://apis.usps.com/oauth2/v3/token

curl -X 'POST' 'https://apis.usps.com/oauth2/v3/token' \
     --header 'Content-Type: application/json' \
     --data '{
		"client_id": "{{CLIENT_ID}}",
		"client_secret": "{{CLIENT_SECRET}}",
		"grant_type": "client_credentials"
		}'

Use the total-rates/search endpoint to get a comprehensive price that includes both the base rate and selected extra services. This endpoint returns multiple rateOptions, each containing a totalBasePrice, a totalPrice (base + extra services), and the specific rates and extraServices used to calculate that total.

curl 　-X 'POST' 'https://apis.usps.com/prices/v3/total-rates/search' \
		--header 'Content-Type: application/json' \
		--header 'Authorization: Bearer $TOKEN' \
		--data '{
			"originZIPCode": "36105",
			"destinationZIPCode": "78207",
			"weight": 7,
			"length": 9,
			"width": 0.25,
			"height": 6,
			"mailClass": "PARCEL_SELECT",
			"priceType": "COMMERCIAL",
			"mailingDate": "2023-07-28",
			"accountType": "EPS",
			"accountNumber": "XXXXXXXXXX",
			"itemValue": 500,
			"extraServices": [
				415
			]
		}'