Transaction Reports

HTTP Request

GET /v2/ledger/developers/{developerId}/transactions/reports

Summary

This operation retrieves all transactions for a specified period of time.

Things to Consider

  1. The report returns the following transaction types:
    • POSTAGE FUND: The funding of your postage account.
    • POSTAGE PRINT: The printing of a label.
    • POSTAGE REFUND: A refund request or the resolution of a refund request.
    • APV-POSTAGE OVERPAID: An APV adjustment for an overpayment.
    • APV-POSTAGE UNDERPAID: An APV adjustment for an underpayment.
  2. Transactions returned via this API can lag up to 24 hours behind the actual transaction date and time.
  3. The transactionId identifies all the transactions associated with a given shipment. A transactionId can appear multiple times in a report. Each occurrence of the transactionId represents a different transaction for the same shipment.
  4. For answers to common questions, please see the Transaction Reports FAQs.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v2/ledger/developers/{developerId}/transactions/reports
Production: https://api.pitneybowes.com/shippingservices/v2/ledger/developers/{developerId}/transactions/reports

Path Parameters

Name Data Type Description
developerId String Required. Your Pitney Bowes developer ID.

Query Parameters

Query parameters are optional.

Name Data Type Description
fromDate ISO 8601 Date Format

The beginning of the date range for transactions.

Note: Specify this value in UTC using the ISO 8601 format. You must include both date and time, and you must end the time with Z to indicate a zero offset.

For example:

fromDate=2016-10-05T00:00:00Z

toDate ISO 8601 Date Format

The end of the date range for transactions.

Note: Specify this value in UTC using the ISO 8601 format. You must include both date and time, and you must end the time with Z to indicate a zero offset.

For example:

toDate=2018-01-02T23:59:00Z

transactionId String

The unique string that identifies all the transactions associated with a given shipment. The string comprises the developer ID and the shipment’s X-PB-TransactionId, separated by an underscore (_).

For example:

transactionId=44397664_ad5aa07-ad7414-a78a-c22b3

TIP: You can search for transactionId by passing the whole string, as described above, or by passing the X-PB-TransactionId alone prefixed by the % symbol, e.g.: %shpmnt3015

parcelTrackingNumber String Parcel tracking number of the shipment.
merchantId String The value of the postalReportingNumber element in the merchant object. This value is also the merchant’s Shipper ID.
transactionType String

Transaction Type. Valid values:

  • POSTAGE FUND: Funding of the postage account.
  • POSTAGE PRINT: Printing of a label.
  • POSTAGE REFUND: A refund request or the resolution of a refund request.
  • APV-POSTAGE ALL: An APV adjustment. (This query value retrieves all APV adjustments.)
  • APV-POSTAGE OVERPAID: An APV adjustment for overpayment.
  • APV-POSTAGE UNDERPAID: An APV adjustment for underpayment.
printStatus String

The status of a USPS SBR (scan-based return) label. Valid values:

  • SBR: All SBR labels, both scanned labels and labels that are printed but not yet scanned into the USPS mailstream.
  • SBRPrinted: SBR labels that are printed but not yet scanned into the mailstream.
  • SBRCharged: SBR labels that are scanned into the mailstream.
size Number Page size of the result set for the specified query filters. Specifically, the number of transactions to return per page in the result set. Default page size is 20.
page Number The index number of the page to return. Page index numbering starts at 0. Specifying page=0 returns the first page of the result set.
sort String

Defines a property to sort on and the sort order. Sort order can be ascending (asc) or descending (desc). Use the following form:

sort=<property_name>,<sort_direction>

For example:

sort=transactionId,desc

Request Headers

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Accept-Language String Language and country code. Default: en-US

Response Elements

Name Data Type Description
content Array[transaction object]

The transactions. Each object in the array is a separate transaction. The transaction object’s elements are described in the next table below.

Note: Multiple transactions can share the same transactionId.

totalPages Number Total Number of pages in the result set.
totalElements Number Total number of transactions in the result set for the specified query filters.
last Boolean If true, this is the last page of the result set.
first Boolean If true, this is the first page of the result set.
numberOfElements Number Number of transactions in the current page.
sort Array[Object] Lists the property used to sort the transactions and the sort order.
size Number Number of transactions per page in the result set. The default size is 20.
number Number The index number of the page being returned. Page index numbering starts at 0. If number is set to 4, this is the 5th page of the result set.

Response Elements: Transaction Object

Name Data Type Description
transactionId String

The ID used to uniquely identify the shipment associated with the transaction. The ID is a combination of the developer ID and the shipment’s X-PB-TransactionId, separated by an underscore (_):

<Developer-ID>_<X-PB-TransactionId>

transactionDateTime ISO 8601 date format Date and time of of the transaction.
transactionType String

Type of transaction. Valid values:

  • POSTAGE FUND: The funding of your postage account.
  • POSTAGE PRINT: The printing of a label.
  • POSTAGE REFUND: A refund request or the resolution of a refund request.
  • APV-POSTAGE OVERPAID: An APV adjustment for an overpayment.
  • APV-POSTAGE UNDERPAID: An APV adjustment for an underpayment.
developerName String Name of the developer account used to print the shipment label.
developerId String The developer ID used to print the shipment label.
developerPostagePaymentMethod String The developer’s PB Postage Account payment method. This is populated only for transactions that use the Bulk Postage Account payment model, as described in Merchant Enrollment.
developerRatePlan String Rate plan of the developer (integrator).
developerRateAmount String

Amount charged to the developer. The amount is based on the developer’s rate plan. If the merchant (shipper) has an NSA, the amount is instead based on the NSA.

APV Adjustments: If the transaction is an APV adjustment, this field is the difference between the charge that was calculated at the time of print and the charge calculated by USPS.

developerPostagePaymentAccountBalance String This field is not used to report data at this time. This field always returns the null value.
merchantName String Name of the merchant.
merchantId String The value of the postalReportingNumber field in the merchant object. This value is also the merchant’s Shipper ID.
merchantPostageAccountPaymentMethod String The merchant’s PB Postage Account payment method. This is populated only for transactions that use the Individual Postage Account payment model, as described in Merchant Enrollment.
merchantRatePlan String Rate plan of the merchant (shipper).
merchantRate String

Amount charged to the merchant. This is based on the merchant’s shipper rate plan.

APV Adjustments: If the transaction is an APV adjustment, this field is the difference between the charge to the merchant calculated at the time of print and the charge calculated based on information from USPS.

shipperPostagePaymentAccountBalance String Postage balance in the merchant’s PB Postage Account.
labelFee String Currently not used.
parcelTrackingNumber String Tracking number.
weightInOunces String Weight in ounces. In the case of an APV adjustment, this is based on the new information received from USPS.
zone String Zone. In the case of an APV adjustment, this is based on the new information received from USPS.
packageLengthInInches String Package length in inches. In the case of an APV adjustment, this is based on the new information received from USPS.
packageWidthInInches String Package width in inches. In the case of an APV adjustment, this is based on the new information received from USPS.
packageHeightInInches String Package height in inches. In the case of an APV adjustment, this is based on the new information received from USPS.
packageTypeIndicator String

Indicates whether cubic pricing was used. Valid values:

  • Cubic
  • NonCubic

In the case of an APV adjustment, this is based on the new information received from USPS.

packageType String Package type. In the case of an APV adjustment, this is based on the new information received from USPS.
mailClass String Mail class or service.
internationalCountryGroup String International country group code.
originationAddress String Origination address.
originZip String Origin postal code.
destinationAddress String Destination address.
destinationZip String Destination postal code.
destinationCountry String Destination country.
postageDepositAmount String Postage deposit amount.
creditCardFee String Credit card fee.
printStatus String

The status of an SBR label:

  • SBRPrinted: The SBR label has been printed but has not been scanned in to the USPS mailstream.
  • SBRCharged: The SBR label has been scanned into the USPS mailstream.
  • NULL: The label is a pre-paid outbound label (i.e., not an SBR label).
shipmentId String The unique identifier for the shipment generated when the shipment was created.
refundStatus String

Refund status. Possible values include:

  • REQUESTED
  • ACCEPTED
  • DENIED

For more information on refunds, see Refunds FAQs.

refundDenialReason String The reason for a refund denial.
refundRequestor String

Indicates who requested the refund.

  • Shipper Requested: The shipper requested the refund.
  • Auto Refund Processor: The transaction is an auto refund.
  • PB Claims: The request is part of the Holiday Guarantee program.
adjustmentReason String

APV Adjustments Only. The reason for an APV adjustment based on the new information received from USPS. Possible reasons are:

  • Weight
  • Dimension
  • Package
  • Zone
  • Duplicate
externalId String

Applies only to the following:

  • APV Adjustments: The unique identifier that USPS assigned to the APV adjustment. If you want to appeal the adjustment, you must send this identifier to USPS. For more information, see How do I dispute an adjustment?.
  • Holiday Guarantee Refunds: The claim number assigned by the the Holiday Guarantee program.

Sample Request

curl -X GET .../v2/ledger/developers/44397664/transactions/reports?fromDate=2018-08-01T00:00:00Z&toDate=2018-08-31T23:59:59Z&sort=parcelTrackingNumber,asc \
-H "Authorization: Bearer <oauth_token>" \
-H "Accept-Language:en-US"

Sample Response

The response below shows three transactions for the same shipment: the printing of the label, the request for a refund, and the approval of the refund request.

{
    "content": [ {
        "transactionId": "44397664_a7-4bc2-a17a-02a37ad84a5d",
        "transactionDateTime": "2018-08-01T02:30:04.025+0000",
        "transactionType": "POSTAGE PRINT",
        "developerName": "Pitney Bowes",
        "developerId": "44397664",
        "developerPostagePaymentMethod": null,
        "developerRatePlan": null,
        "developerRateAmount": 3.5,
        "developerPostagePaymentAccountBalance": null,
        "merchantName": "Shipper3",
        "merchantId": "9047625930",
        "merchantPostageAccountPaymentMethod": "OTHER",
        "merchantRatePlan": null,
        "merchantRate": null,
        "shipperPostagePaymentAccountBalance": 1803.41,
        "labelFee": null,
        "parcelTrackingNumber": "0400109205168000244595",
        "weightInOunces": 10,
        "zone": "",
        "packageLengthInInches": 6,
        "packageWidthInInches": 6,
        "packageHeightInInches": 6,
        "packageTypeIndicator": "NonCubic",
        "packageType": "PKG",
        "mailClass": "First-Class Mail",
        "internationalCountryPriceGroup": null,
        "originationAddress": "27 Waterview Dr,Shelton,CT,06484",
        "originZip": "06484",
        "destinationAddress": "625 S Main St,Greenville,SC,29601",
        "destinationZip": "29601250431",
        "destinationCountry": "US",
        "postageDepositAmount": null,
        "creditCardFee": null,
        "refundStatus": null,
        "refundDenialReason": null,
        "printStatus": null,
        "shipmentId": "USPS2200487400865080",
        "refundRequestor": null,
        "externalId": null,
        "adjustmentReason": null
    },
    {
        "transactionId": "44397664_a7-4bc2-a17a-02a37ad84a5d",
        "transactionDateTime": "2018-08-02T00:00:00.000+0000",
        "transactionType": "POSTAGE REFUND",
        "developerName": "Pitney Bowes",
        "developerId": "44397664",
        "developerPostagePaymentMethod": null,
        "developerRatePlan": null,
        "developerRateAmount": 3.5,
        "developerPostagePaymentAccountBalance": null,
        "merchantName": "Shipper3",
        "merchantId": "9047625930",
        "merchantPostageAccountPaymentMethod": "OTHER",
        "merchantRatePlan": null,
        "merchantRate": null,
        "shipperPostagePaymentAccountBalance": 1547.53,
        "labelFee": null,
        "parcelTrackingNumber": "0400109205168000244595",
        "weightInOunces": 10,
        "zone": "",
        "packageLengthInInches": 6,
        "packageWidthInInches": 6,
        "packageHeightInInches": 6,
        "packageTypeIndicator": "NonCubic",
        "packageType": "PKG",
        "mailClass": "First-Class Mail",
        "internationalCountryPriceGroup": null,
        "originationAddress": "27 Waterview Dr,Shelton,CT,06484",
        "originZip": "06484",
        "destinationAddress": "625 S Main St,Greenville,SC,29601",
        "destinationZip": "29601250431",
        "destinationCountry": "US",
        "postageDepositAmount": null,
        "creditCardFee": null,
        "refundStatus": "REQUESTED",
        "refundDenialReason": null,
        "printStatus": null,
        "shipmentId": "USPS2200487400865080",
        "refundRequestor": "Shipper Requested",
        "externalId": null,
        "adjustmentReason": null
    },
    {
        "transactionId": "44397664_a7-4bc2-a17a-02a37ad84a5d",
        "transactionDateTime": "2018-08-14T11:19:20.864+0000",
        "transactionType": "POSTAGE REFUND",
        "developerName": "Pitney Bowes",
        "developerId": "44397664",
        "developerPostagePaymentMethod": null,
        "developerRatePlan": null,
        "developerRateAmount": 3.5,
        "developerPostagePaymentAccountBalance": null,
        "merchantName": "Shipper3",
        "merchantId": "9047625930",
        "merchantPostageAccountPaymentMethod": "OTHER",
        "merchantRatePlan": null,
        "merchantRate": 3.5,
        "shipperPostagePaymentAccountBalance": 1700.97,
        "labelFee": null,
        "parcelTrackingNumber": "0400109205168000244595",
        "weightInOunces": 10,
        "zone": "",
        "packageLengthInInches": 6,
        "packageWidthInInches": 6,
        "packageHeightInInches": 6,
        "packageTypeIndicator": "NonCubic",
        "packageType": "PKG",
        "mailClass": "First-Class Mail",
        "internationalCountryPriceGroup": null,
        "originationAddress": "27 Waterview Dr,Shelton,CT,06484",
        "originZip": "06484",
        "destinationAddress": "625 S Main St,Greenville,SC,29601",
        "destinationZip": "29601250431",
        "destinationCountry": "US",
        "postageDepositAmount": null,
        "creditCardFee": null,
        "refundStatus": "ACCEPTED",
        "refundDenialReason": null,
        "printStatus": null,
        "shipmentId": "USPS2200487400865080",
        "refundRequestor": "Shipper Requested",
        "externalId": null,
        "adjustmentReason": null
    }, ... ],
    "totalPages": 2,
    "totalElements": 37,
    "last": false,
    "first": true,
    "numberOfElements": 20,
    "sort": [ {
        "direction": "ASC",
        "property": "parcelTrackingNumber",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": true
    } ],
    "size": 20,
    "number": 0
}

Error Codes

The following error code is specific to Transaction Reports.

Error Code Error Message Solution
invalid.date.time Provided Date/time ___ is invalid, valid format is YYYY-MM-DDThh:mm:ss.sZ See the explanations of fromDate and toDate above in Query Parameters.

For a list of all PB Shipping APIs error codes, see Error Codes.