Access PB Cross-Border via Manifest Files

Overview

You can use SFTP to send shipment information to Pitney Bowes.

Send the Manifest File

To send a manifest file to Pitney Bowes, complete the following steps:

  1. Create your JSON file.

    To download the file specification, click here.

  2. Upload the JSON file to our SFTP server. This file should contain all parcels shipped to our consolidation center.

  • After your file has been uploaded to our server, we will process the records line-by-line for the entire file.
    • If the file has been successfully processed, we will send an .ok file (same file name with the .ok extension) in response.
    • If there are any errors on any lines within the file, we will continue processing the file; however, we will record the error and, in response, respond with an .err file (same file name with the .err extension).
      • If the file format is wrong, or does not conform to our naming convention, or does not parse, we will reject the file. For more information on how to name the file, see File-Naming Conventions.
  • All the data, message and log files transferred between Pitney Bowes and your business follows a special naming convention. These files are detailed below:
    • .ok – The .ok file indicates that we have successfully processed your JSON file. The OK file contains the following pieces of information:
      • Date-Time Stamp – The date and time (in the UTC time zone) for when the file was processed.
      • Number of Records – The total number of records successfully processed.
    • .err – The .err file indicates that we were not able to process some or all of the records in your JSON file, due to errors. The error file contains the following pieces of information:
      • Date-Time Stamp – The date and time (in the UTC time zone) for when a data record was processed.
      • Record Number – The line number in the file for the record in error.
      • Error Code – A predefined code (e.g. INVALID_FILE_FORMAT) that identifies an error. An UNKNOWN or NULL value may be specified if the error is not known, or if the error is undefined.
      • Details – An optional field carrying additional information about the error. This field may carry a brief error description (especially when the error code is unavailable) or the original input record as a reference.
      • Context_Field_Name – An optional field containing a field name in error.
      • Context_Field_Value – An optional field containing the value of a field name in error.
  1. If there are any errors in your file and you receive an .err file in response from our server, submit a replacement file for the shipment notification.
  • In this replacement file, please only submit “fixed” records; that is, records that were in error in the original file. Please do not submit partial updates for these error records.
  1. If you receive an .ok file in response from our server, then there are no errors in your file, and your shipment notifications have been fully received!
  • To avoid clutter in your inbound folder, we recommended marking all .ok files as “processed” and moving these files to an archive folder.

The following diagram depicts an overview of the manifest file exchange process, highlighting the touch points between your business and Pitney Bowes (click image to enlarge).

Pitney Bowes SFTP diagram

File-Naming Conventions

All data, message, and log files transferred between your business and Pitney Bowes must follow a special naming convention. Before transferring your JSON file to our server, please ensure that your file is named appropriately, as shown in the example below. All characters in the filename should be separated by an underscore (e.g., “_”) and be in lower case.

<Sender_ID>_<Data_Feed_Name>_<Operation>_<Recipient_ID>_<UTC_Date_Time>_<Random_6_Digits>.<File_Extension>

For more information on the structure of the file name, please refer to the below table.

Name Description
Sender_ID A pre-authorized business ID that identifies your business.
Data_Feed_Name

Predefined name of the data feed, detailed as follows:

  • “shipment-details”: Shipment manifest file generated by your business.
  • “transaction-details”: Transaction details feed generated by Pitney Bowes.
  • “shipment-response” : Shipment response feed for successfully processed records in the manifest file.
  • “tracking-update”: Tracking file feed generated by Pitney Bowes.
Operation

The operation to perform, detailed as follows:

  • “update” – Records will be updated if exist by the given primary key, otherwise inserted.
  • “delete” – Records exist by the given primary key will be removed, otherwise ignored.
Recipient_ID A pre-authorized business ID that identifies Borderfree (e.g., 16061).
UTC_Date_Time The date and time when the data file was published. It is defined in the UTC time format (e.g., “YYYYMMDD”).
Random_6_Digits A 6-digit random number that ensures that the file name is unique.
File_Extension File extension that identifies the file type/format. (Only “zip”, “csv”, “json” file types are allowed.)

For examples of this format, please refer to the below table with an example Sender_ID of GS00001.

From / To Feed type File
From your business to Pitney Bowes shipment-details GS00001_shipment-details_update_16061_20181001_131530_123456.json
From your business to Pitney Bowes category-tree GS00001_category-tree_update_16061_20181001_131530_123456.json
From Pitney Bowes to your business tracking-update 16061_tracking-update_update_GS00001_20181001_140346_966998.csv
From Pitney Bowes to your business tx-details 16061_tx-details_update_GS00001_20181001_140346_966998.csv