Get Archived Reports

HTTP Request

GET /v4/ledger/developers/{developerId}/transactions/archived

Summary

This operation retrieves transaction history that is older than 6 months.

Note: For transaction history within the last 6 months, use the Get Transaction Reports API.

Considerations

1. This API returns transactions for shipments where rates.carrier is equal to USPS.

2. You must provide a date through the query parameters. You must provide either a fromDate or toDate, or both.

   If you provide one date parameter and not the other, the API will return 31 days of data. The missing parameter will default to 31 days from the given parameter.

3. The date range cannot cannot exceed 92 days, unless you specify a transactionId or parcelTrackingNumber, in which case there is no limit on the date range.

4. Transactions are returned in UTC/GMT time.

5. All transactions for a given shipment use the same transactionId. Therefore, a given transaction ID can appear multiple times in a report. Each occurrence represents a different transaction for the same shipment.

   The transactionId comprises the developer ID and the shipment’s X-PB-TransactionId, separated by an underscore:

   <developer_id>_<X-PB-TransactionId>
   

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v4/ledger/developers/{developerId}/transactions/archived
Production: https://shipping-api.pitneybowes.com/shippingservices/v4/ledger/developers/{developerId}/transactions/archived

Path Parameter

Name	Description
developerId	Required. Your Pitney Bowes developer ID.

Query Parameters

A date parameter is required. You must provide a fromDate, a toDate, or both.

Name	Description
fromDate	The beginning of the date range for the returned transactions. Specify this value in UTC using the ISO 8601 standard. The value must include both date and time and must end with Z to indicate the zero offset. For example: fromDate=2019-10-05T00:00:00Z You must specify either a fromDate or toDate. If this is not specified, the value defaults to 31 days before the toDate. The date range cannot cannot exceed 92 days, unless you specify a transactionId or parcelTrackingNumber.
merchantId	Returns all transactions for a specific merchant. Enter the merchant’s Shipper ID. The Shipper ID is found in the postalReportingNumber field, retrieved through the Get Merchants API.
page	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.
parcelTrackingNumber	Returns all transactions associated with a specific label. The parameter identifies the label by the shipment’s tracking number.
shipDetails	If set to 1, the API returns the following fields for each transaction: dimensionalWeightOz valueOfGoods specialServices customMessage1 customMessage2 If set to 0, the fields are not returned. Default Value: 0
size	The number of transactions to return per page in the result set. Default Value: 20
toDate	The end of the date range for the returned transactions. Specify this value in UTC using the ISO 8601 standard. The value must include both date and time and must end with Z to indicate a zero offset. For example: toDate=2019-11-02T23:59:00Z You must specify either a fromDate or toDate. If this is not specified, the value defaults to 31 days after the fromDate. The date range cannot cannot exceed 92 days, unless you specify a transactionId or parcelTrackingNumber.
transactionId	Returns all transactions associated with a specific label. The parameter identifies the label by a string that comprises the developer ID and the shipment’s X-PB-TransactionId, separated by an underscore (_): <developer_ID>_<X-PB-TransactionId> For example: 12345678_ad507ef7414a78ac22b3
transactionType	Returns all transactions of a given transaction type. Valid values: POSTAGE FUND: The funding of a postage account. POSTAGE PRINT: The printing of a label. POSTAGE REFUND: A refund request or the resolution of a refund request. FEE: An ACH return fee. The status field indicates whether the fee was processed or waived. APV-POSTAGE ALL: Any APV adjustment, including both overpays and underpays. APV-POSTAGE OVERPAID: An APV adjustment for overpayment. APV-POSTAGE UNDERPAID: An APV adjustment for underpayment. APV-DISPUTE ADJUSTMENT: A dispute of an APV-POSTAGE UNDERPAID transaction. CREDIT ADJUSTMENT: A manual credit. DEBIT ADJUSTMENT: A manual debit.

Request Headers

Name	Description
Authorization	Required. OAuth token generated using the Generate an OAuth Token API.
Accept-Language	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 is described in the next table below. Note: Multiple transactions can share the same transactionId.
searchCriteria	Object	The query parameters and the developer ID. The following is returned for a query on merchantId and transactionType: { "developerId": "12345678", "merchantId": "9024324564", "transactionType": "POSTAGE PRINT", "fromDate": "2019-08-01T02:00:00.000+0000", "toDate": "2019-11-01T02:00:00.000+0000" } Note that the object always returns the fromDate and toDate parameters, even if you leave them out of the query.
last	Boolean	If true, this is the last page of the result set.
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.
sort	Array[Object]	An object with information about the sort order.
numberOfElements	Number	Number of transactions in the current page.
first	Boolean	If true, this is the first page of the result set.
size	Number	Number of transactions per page in the result set. Default: 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.

Transaction Object (Archived Reports API)

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	String	The date and time of the transaction, returned in UTC/GMT using the ISO 8601 standard.
transactionType	String	Type of transaction. Valid values: POSTAGE FUND: The funding of a postage account. POSTAGE PRINT: The printing of a label. POSTAGE REFUND: A refund request or the resolution of a refund request. FEE: An ACH return fee. The status field indicates whether the fee is processed or waived. APV-POSTAGE OVERPAID: An APV adjustment for overpayment. APV-POSTAGE UNDERPAID: An APV adjustment for underpayment. APV-DISPUTE ADJUSTMENT: A dispute of an APV-POSTAGE UNDERPAID transaction. CREDIT ADJUSTMENT: A manual credit. DEBIT ADJUSTMENT: A manual debit.
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 applies only to transactions that use the Bulk Postage Account payment model, as described in Merchant Enrollment Models.
developerRatePlan	String	Rate plan of the developer.
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 currently used.
merchantName	String	Name of the merchant.
merchantId	String	The value of the postalReportingNumber field retrieved through the Get Merchants API. This value is also the merchant’s Shipper ID.
merchantPostageAccountPaymentMethod	String	The merchant’s PB Postage Account payment method. This applies only to transactions that use the Individual Postage Account payment model, as described in Merchant Enrollment Models.
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. This is the ending balance after this transaction was processed. If the merchant’s postage balance is currently negative, the merchant must refill the postage account. See How do I fill my PB Postage Account with funds?
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	The parcel type. For supported parcel types, see the carrier page for the carrier you are using. In the case of an APV adjustment, this is based on the new information received from USPS.
mailClass	String	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.
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.
printStatus	String	For a PB Expedited Returns label, the label’s status. Possible values: Printed: The label has been printed but not used. Charged: The label has been used. Note: This information also appears in the status field.
shipmentId	String	The unique identifier for the shipment generated when the shipment was created.
refundRequestor	String	Indicates who requested the refund. Shipper Requested: The shipper requested the refund. PB Claims: The request is part of the Delivery Guarantee program.
externalId	String	This applies only to the following: APV adjustments: The USPS Revenue Assurance ID assigned to the APV adjustment in case of a dispute. PB Delivery Guarantee: This is an ID beginning with “PBD” and followed by sequence of numbers. This indicates a Delivery Guarantee credit.
adjustmentReason	String	This applies only to APV adjustments and gives the reason for the adjustment based on information received from USPS. Possible values are: weight. Incorrect weight listed when creating the label. dimension: Incorrect dimensions listed when creating the label. package: Incorrect parcel type listed when creating the label. zone: Incorrect origin or induction postal code listed when creating the label. duplicate: The label had already been inducted. The IMpb tracking barcode was entered into the USPS mailstream more than once within 120 days. The transaction report includes the charges for the additional use of the label. usedRefundedLabel: The label was a refunded label that was then entered into the USPS mailstream. The transaction report includes the charges for using the label after having voided it.
meterNumber	String	Internal identification number for the postage meter that was used.
dimensionalWeightOz	BigDecimal	The dimensional weight, if applicable. To return this field, set the shipDetails query parameter to 1.
valueOfGoods	BigDecimal	The value provided in the parcel.valueOfGoods field in the Create Shipment request, if applicable. To return this field, set the shipDetails query parameter to 1.
specialServices	Array[Special Services Object]	This array contains the shipment’s special services, including the fee paid for each service. To return this field, set the shipDetails query parameter to 1.
status	String	The transaction status for the following types of transactions: ACH transaction. Possible values: Pending: A POSTAGE FUND transaction is pending. Processed: Either a POSTAGE FUND or a FEE transaction has been processed. Returned: A POSTAGE FUND transaction failed. Waived: A FEE has been waived. APV dispute. Possible values: REQUESTED ACCEPTED DENIED PB Expedited Returns label. Possible values: Printed Charged
description	String	Details on the status of an ACH transaction. Possible values: Postage Fund Pending: A POSTAGE FUND transaction is pending. Postage Fund Processed: A POSTAGE FUND transaction has been processed. Postage Fund Returned: A POSTAGE FUND transaction failed. ACH Return Fee Processed: A FEE has been processed. ACH Return Fee waived: A FEE has been waived.
clientFacilityId	String	For a PB Standard transaction, this is the ID that was assigned to the merchant’s facility during onboarding with PB Standard.
carrierFacilityId	String	For a PB Standard transaction, this is the ID of the PB Standard facility that was assigned to the merchant during onboarding with PB Standard.
inductionPostalCode	BigDecimal	The postal code where the shipment was tendered to the carrier. To return this field, set the shipDetails query parameter to 1.
tracking	Object	For a POSTAGE PRINT transaction, this object returns the most recent tracking event within 30 days of the transaction’s date and time. To return this object, include the trackingStatus query parameter in the request. Note: This object is not returned by the Get Archived Reports API.
tracking.parcelStatus	String	The most recent tracking event within 30 days of the parcel’s ship date. This is the same information returned in the status field of the Tracking API. Note: Transaction Reports record tracking status only for the first 30 days after the parcel’s ship date.
tracking.statusDate	String	The local date and time where the tracking event occurred. This is the same information returned in updatedDate and updatedTime in the Tracking API.
customMessage1	String	The message specified in the PRINT_CUSTOM_MESSAGE_1 shipment option in the Create Shipment request. To return this field, set the shipDetails query parameter to 1.
customMessage2	String	The message specified in the PRINT_CUSTOM_MESSAGE_2 shipment option in the Create Shipment request. To return this field, set the shipDetails query parameter to 1.

Sample Request

Archived Reports Sample Request

curl -X GET ".../v4/ledger/developers/12345678/transactions/archived?fromDate=2019-04-01T00:00:01Z&shipDetails=1" \
-H "Authorization: Bearer <oauth_token>" \
-H "Accept-Language:en-US"

Archived Reports Sample Response

{
    "content": [ {
        "transactionId": "12345678_s1846423",
        "transactionDateTime": "2019-04-16T13:33:58.972+0000",
        "transactionType": "POSTAGE PRINT",
        "developerName": "PB",
        "developerId": "12345678",
        "developerPostagePaymentMethod": null,
        "developerRatePlan": null,
        "developerRateAmount": 48.600,
        "developerPostagePaymentAccountBalance": null,
        "merchantName": "Jones",
        "merchantId": "9024324564",
        "merchantPostageAccountPaymentMethod": "OTHER",
        "merchantRatePlan": null,
        "merchantRate": null,
        "shipperPostagePaymentAccountBalance": 475.160,
        "labelFee": null,
        "parcelTrackingNumber": "9405509898644503696569",
        "weightInOunces": 1,
        "zone": "6",
        "packageLengthInInches": 36.000,
        "packageWidthInInches": 12.000,
        "packageHeightInInches": 12.300,
        "packageTypeIndicator": "NonCubic",
        "packageType": "PKG",
        "mailClass": "Priority Mail",
        "internationalCountryPriceGroup": null,
        "originationAddress": "545 Market St,San Francisco,CA,94105",
        "originZip": "94105",
        "destinationAddress": "284 W Fulton St,Garden City,KS,67846",
        "destinationZip": "67846535284",
        "destinationCountry": "US",
        "postageDepositAmount": null,
        "creditCardFee": null,
        "refundStatus": null,
        "refundDenialReason": null,
        "printStatus": null,
        "shipmentId": "USPS2200250326735036",
        "refundRequestor": null,
        "externalId": null,
        "adjustmentReason": null,
        "meterNumber": "0001259113",
        "dimensionalWeightOz": 432,
        "valueOfGoods": 0.000,
        "specialServices": [ {
            "specialServiceId": "Ins",
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ]
        },{
            "specialServiceId": "DelCon",
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ]
        } ],
        "status": null,
        "description": null,
        "customMessage1": null,
        "customMessage2": null
    },
    ...
    ],
    "searchCriteria": {
        "developerId": "12345678",
        "fromDate": "2019-04-01T00:00:01.000+0000",
        "toDate": "2019-05-02T00:00:01.000+0000",
        "shipDetails": 1
    },
    "last": false,
    "totalElements": 88,
    "totalPages": 5,
    "first": true,
    "numberOfElements": 20,
    "sort": [ {
        "direction": "ASC",
        "property": "transactionDateTime",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "descending": false,
        "ascending": true
    } ],
    "size": 20,
    "number": 0
}

Error Codes

The following error code is specific to reports:

Error Code	Error Message	Solution
invalid.date.time	Date range can not exceed 3 months. From date: ___ To date: ___	See Query Parameters for allowed range.
invalid.date.time	Provided Date/time ___ is invalid, valid format is YYYY-MM-DDThh:mm:ss.sZ	See Query Parameters for correct format.

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

 
 
 
 

• next
• previous |

© Copyright 2024 Pitney Bowes Inc. All rights reserved.