Expedited Billing Extract File

← Shipping FAQs

Overview

The Billing Extract File (BEF) is a CSV file that provides data on your transactions for the previous week. You can download the file from Client Connect. Pitney Bowes provides the new BEF every Monday for the transactions that occurred the previous Sunday through Saturday.

File-Naming Convention

The Billing Extract File uses the following file-naming convention:

PB-<INVOICE_DATE>-<SHIPPER_NAME>-invoice-<INVOICE_NUMBER>-expedited-details

where,

<INVOICE_DATE> is replaced by the invoice date,
<SHIPPER_NAME> is replaced by the Shipper ID, and
<INVOICE_NUMBER> is replaced by the invoice number.

For example:

PB-20230518-mycorp-invoice-1023125522-expedited-details

BEF Header

The first line in the BEF is the header and contains the BEF’s field names. The following is the first line in the BEF:

DOCUMENT_NO,DOCUMENT_DATE,SHIPPER_ID,SHIPPER_NAME,SHIPMENT_ID,TRANSACTION_ID,TRANSACTION_DATETIME (UTC),TRANSACTION_TYPE,STATUS,CARRIER,MAIL_CLASS,PACKAGE_TYPE,TRACKING_NO,LENGTH,WIDTH,HEIGHT,WEIGHT,WEIGHT_UOM,DIM_WEIGHT,DIM_WEIGHT_UOM,ORIGIN_ZIP,ORIGIN_ADDRESS,INDUCTION_POSTAL_CODE,USPS_ZONE,DESTINATION_COUNTRY,DESTINATION_ZIP,INTERNATIONAL_ZONE,ORIGINAL_DOCUMENT_NO,ADJUSTMENT_REASON,ADJUSTMENT_EXTERNAL_ID,CUSTOM_MESSAGE_1,CUSTOM_MESSAGE_2,ITEM_TYPE,INCURRED_DATE (ET),CURRENCY,SERVICE_TYPE,NOTES,UNIT_PRICE,QUANTITY,SERVICE_SUBTOTAL,LABEL_FEE_PRICE,LABEL_FEE_QUANTITY,LABEL_FEE_SUBTOTAL,PAYMENT_PROCESSING_FEE_PRICE,PAYMENT_PROCESSING_FEE_QUANTITY,PAYMENT_PROCESSING_FEE_SUBTOTAL,SERVICE_PLUS_FEES_SUBTOTAL,TAX_RATE,TAX_AMOUNT,TOTAL,SPECIAL_SERVICES,DOCUMENT_LINE_ITEM_NO,DOCUMENT_TOTAL

Transaction Data

After the header, each subsequent line in the BEF is a separate transaction, with the transaction’s data separated by commas. Each transaction contains values for the fields listed in the header. For field definitions, see the BEF Field Specification below. If a field has no value, a comma appears without accompanying data.

The following is a sample BEF transaction:

"1023125522",2023-05-13,"9024324564","MyCorp","USPS1116859175603870","45678123_9024324564_2426656",2023-05-07T22:39:53Z,"POSTAGE PRINT","","USPS","Priority Mail","PKG",'9400109105155564154904,9.00,4.00,6.00,16.4800,"OZ",0.0000,"OZ","60502","2360 Mayfair Dr,Salina,KS,67401-6801","32301","6","US","02842539054","","","","","","SHMBR040","DEBIT","2023-05-10","USD","USPS Label - Priority Mail","",4.44,1,4.44,0.00,0,0.00,0.00,0,0.00,4.44,,,4.44,"[{specialServiceId:DelCon,fee:0}]","7",12327.95

BEF Field Specification

Each line in the BEF provides data for the following fields, in the order listed here:

Field

Format

Length

Description

DOCUMENT_NO

Alpha-numeric

40

The invoice number generated by SAP.

DOCUMENT_DATE

Date

The invoice date generated by SAP.

SHIPPER_ID

Alpha-numeric

12

The merchant’s Shipper ID.

SHIPPER_NAME

Alpha-numeric

255

The merchant’s name.

SHIPMENT_ID

Alpha-numeric

100

The unique identifier for the shipment, generated when the shipment was created.

TRANSACTION_ID

Alpha-numeric

50

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>

TRANSACTION_DATETIME (UTC)

DateTime

The date and time of the transaction, returned in UTC/GMT using the ISO 8601 standard.

TRANSACTION_TYPE

Alpha-numeric

100

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.

STATUS

Alpha-numeric

100

The status of the transaction.

For an ACH transaction, the possible values are:

  • 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.

For an APV dispute, the possible values are:

  • REQUESTED

  • ACCEPTED

  • DENIED

For an Expedited Returns label, the possible values are:

  • Printed

  • Charged

CARRIER

Alpha-numeric

20

Expedited transactions are currently only USPS. This may be NULL for some transaction types.

MAIL_CLASS

Alpha-numeric

50

Mail class or service.

PACKAGE_TYPE

Alpha-numeric

20

The parcel type. For supported parcel types, see the carrier’s reference page. In the case of an APV adjustment, this is based on the new information received from USPS.

TRACKING_NO

Alpha-numeric

50

Carrier tracking number

LENGTH

Decimal

19,6

Package dimension: length

WIDTH

Decimal

19,6

Package dimension: width

HEIGHT

Decimal

19,6

Package dimension: length

WEIGHT

Decimal

19,6

Package weight

WEIGHT_UOM

Alpha-numeric

2

Unit of measurement for package weight

DIM_WEIGHT

Decimal

19,6

Dimensional weight. Used for cubic pricing.

DIM_WEIGHT_UOM

Alpha-numeric

2

Unit of measurement for dimensional weight.

ORIGIN_ZIP

Alpha-numeric

20

ORIGIN_ADDRESS

Alpha-numeric

255

INDUCTION_POSTAL_CODE

Alpha-numeric

20

The postal code where the shipment was tendered to the carrier.

USPS_ZONE

Alpha-numeric

2

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

DESTINATION_COUNTRY

Alpha-numeric

2

DESTINATION_ZIP

Alpha-numeric

11

INTERNATIONAL_ZONE

Alpha-numeric

10

International country group code.

ORIGINAL_DOCUMENT_NO

Alpha-numeric

40

Populated for Refunds. This is the original invoice number on which the label print charge appeared.

ADJUSTMENT_REASON

Alpha-numeric

255

APV Only. The reason for an APV 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.

ADJUSTMENT_EXTERNAL_ID

Alpha-numeric

50

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.

CUSTOM_MESSAGE_1

Alpha-numeric

128

CUSTOM_MESSAGE_2

Alpha-numeric

128

ITEM_TYPE

Alpha-numeric

20

Values are Debit or Credit. Debit is a charge to the customer. Credit is a refund or credit adjustment.

INCURRED_DATE (ET)

Date

The date in the Eastern time zone when the charge for the transaction was processed.

CURRENCY

Alpha-numeric

3

SERVICE_TYPE

Alpha-numeric

255

This is a amalgamated output result based on 11 (Carrier), 12 (Mail Class) and 13 (Package Type).

NOTES

Alpha-numeric

255

UNIT_PRICE

Money

10,3

For Expedited transactions, Unit_Price will always be the single transaction value. It’s not relevant to Service Type.

QUANTITY

Integer

For Expedited transactions, Quantity will always be “1”

SERVICE_SUBTOTAL

Money

10,3

LABEL_FEE_PRICE

Money

10,3

If a label fee is being charged, this is the label fee amount.

LABEL_FEE_QUANTITY

Integer

Always set to “1” for Expedited if there is a label fee.

LABEL_FEE_SUBTOTAL

Money

10,3

Quantity * Price. This will be the same as Label Fee Price.

PAYMENT_PROCESSING_FEE_PRICE

Money

10,3

If a payment processing fee is being charged, this is the label fee amount.

PAYMENT_PROCESSING_FEE_QUANTITY

Integer

Always set to “1” for Expedited if there is a payment processing fee.

PAYMENT_PROCESSING_FEE_SUBTOTAL

Money

10,3

Quantity * Price. This is the same as the payment processing fee Price.

SERVICE_PLUS_FEES_SUBTOTAL

Money

10,3

The total AR for this row.

TAX_RATE

Alpha-numeric

Not used for Expedited

TAX_AMOUNT

Money

Not used for Expedited

TOTAL

Money

This is the same as SERVICE_PLUS_FEES_SUBTOTAL.

SPECIAL_SERVICES

Alpha-numeric

16777216

Special Service fees detail as applied to this label price. Informational only.

DOCUMENT_LINE_ITEM_NO

Integer

Not used for Expedited

DOCUMENT_TOTAL

Money

10,3

The invoice total. It is included on every line for EDI purposes.