Subscription Agreement Report Specification

DocsCurrentLast updated: October 12th 2021, @ 6:58:00 pm


The Subscription Agreement Report (SUB) is for use by merchants or payment processing partner, who have integrated the Subscription and Recurring Billing Product. The Subscription Agreement Report gives merchants and processing partners detailed information about outstanding subscribed monthly payments.

Associated specification and documentation

The Subscription Agreement Report is available through PayPal’s website and the Secure FTP Server, which is defined and described in the Secure FTP Server Specification. Subscriptions are created with PayPal Subscriptions and Recurring Billing, as documented in the Subscriptions and Recurring Billing Integration Guide.

Distribution and access

The SUB is available via PayPal's website and the Secure FTP Server (reports.paypal.com), which requires a separate user account for access to the SUB. A user account that is enabled for the SUB is also enabled to create user accounts for the Secure Drop-Box. To ensure data security, SUB users must generate their own user accounts for the Secure Drop-Box.

The following steps describe how to set up and access the SUB using the Secure FTP Server:

  1. Create a Secure FTP Server user account. Login to PayPal (www.paypal.com) and create a Secure PayPal Reporting FTP Server username and password. Passwords for accessing the Secure FTP Server cannot be reset by PayPal. To obtain a new password, you must create a new Secure FTP Server user account.

  2. Grant access to third-party users. You must explicitly grant access to third-parties by contacting their PayPal Account Manager to supply the following information:

    • Third-parties’ PayPal login username
    • Type of permission: reporting access (read)

The third-party is then notified by email that access to the business partner’s Secure FTP Server has been granted.

  1. Access the Secure FTP Server programatically using an FTP client. The hostname of the Secure FTP Server is reports.paypal.com. A user account on the Secure FTP Server has the following directory structure:

/ppreports/outgoing

Schedule

The SUB is generated and delivered by PayPal on a regular (24 hour) basis. With the initial release of the SUB, the SUB is generated and distributed by 9AM daily in the leading timezone of the reporting window.

Data format

You can receive the SUB in either comma separated value (csv) or tab delimited values format. Contact your PayPal Account Manager to set the data format for this report.

Character encoding: UTF-8

The report’s character encoding is UTF-8 (8-bit UCS/Unicode Transformation Format).

Report filename

The filename naming convention depends on whether or not you are using Multiple Account Management.

Single account report

The filename of the SUB for a single account follows this naming convention: SUB-yyyymmdd.reportingWindow.sequenceNumber.totalFiles.version.format

Table 1.1 Subscription Agreement Report File Naming Conventions

SUBAn abbreviation for "Downloadable Subscription Agreement Report."
yyyymmddThe date on the data in the report.
This date stamp represents the latest, or ending date, of the data.
sequenceNumberThe sequence number of this file. Two characters, right-justified and zerofilled. The sequence number begins with 01 and continues until all parts are recorded in files.
The sequence number is always present in the report file name even if there is only one file.
versionThe version of the report. Three characters, right-justified and zero-filled.
formatOne of the following:
  • CSV: a comma-separated value file
  • TAB: a tab-delimited-field file
  • Multiple account report

    When using Multiple Account Management, the filename of the report follows this naming convention: SUB-yyyymmdd.reportingWindow.sequenceNumber.totalFiles.version.format

    TABLE 1.2 Subscription Agreement Report File Naming Conventions

    SUBAn abbreviation for "Downloadable Subscription Agreement Report."
    yyyymmddThe date on the data in the report. This date stamp represents the latest, or ending date, of the data.
    reportingWindowThe window of time when the report was generated, as follows:
      X: GMT 00:00 to GMT -0500
      A: GMT -0500 to GMT-0800
      H: GMT-0800 to GMT +0800
      R: GMT +0800 to GMT 00:00
    sequenceNumber
      The sequence number of this file. Two characters, right-justified and zero-filled. The sequence number begins with 01 and continues until all parts are recorded in files.
      The sequence number is always present in the report file name even if there is only one file.
    totalFilesThe total number of files of the report for this date. The number of files is always two digits and zero-padded. For example, for 2 total files,totalFiles is 02.
    versionThe version of the report. Three characters, right-justified and zero-filled.
    formatOne of the following:
      CSV: a comma-separated value file
      TAB: a tab-delimited-field file

    Data retention

    The SUB is available via the Secure FTP Server for 45 days after the date of its delivery.

    New or revised versions

    In the future, PayPal will support multiple versions of the SUB. PayPal will notify you regarding the creation of any new version as well as any deprecation of older versions of the report.

    If you wish to take advantage of a new version, you can receive two versions of the same report concurrently in order to test and integrate the new version. You can also receive nonconsecutive versions of the same report concurrently in order to test and integrate the new version. Contact your PayPal Account Manager to enable different versions and request any changes in report distribution.

    Notifications

    PayPal operationally monitors the generation and delivery of the SUB on a 24/7 365 basis. PayPal maintains two different user contact points for report notifications:

    • A business contact point for all notifications related to data integrity, data delivery, and new reporting features
    • A technical contact for all notifications related to data integrity, data delivery, system outages, system updates, and new features. PayPal will notify you of the following events related to reporting.
    • Delays in report delivery
    • Errors in report generation
    • New version availability
    • System outage
    • System update / maintenance (pre-announcement)
    • New reporting feature releases

    Contact your PayPal Account Manager to provide PayPal with the appropriate notification email alias. PayPal strongly recommends that you create a distribution list or email alias that allows multiple parties to receive communication about the SUB.

    File structure

    The report can be delivered as either a comma-separated values or tab-delimited file. This section describes the structure of the data file.

    A report file can contain a maximum of 1 million records. If the report contains more than 1 million records, the report is split across multiple files. The report is also organized by section, where each section represents a single PayPal account. If you are not using PayPal Multiple Account Management, the report contains only a single section.

    Each row of the report consists of a two letter row type, followed by the details specific to that row type. Table 1.3, "Report Row Types," lists the valid row types, along with the sections that describe the data for that row type.

    TABLE 1.3 Report tow types

    CodeDescriptionSection
    RHReport headerReport Header Data
    FHFile headerFile Header Data
    SHSection headerSection Header Data
    CHColumn header
    SBRow dataSection Body Data
    SFSection FooterSection Footer Data
    SCSection record countSection Record Count Data
    RFReport footerReport Footer Data
    RCReport record countReport Record Count Data
    FFFile footerFile Footer Data

    A report file with fewer than 1 million records (a single file) with only one section is organized as follows:

    Report Header (RH) File Header (FH) Section Header (SH) Column Header (CH) Row Data (SB) ... Row Data (SB) Section Footer (SF) Section Record Count (SC) Report Footer (RF) Report Record Count (RC) File Footer (FF)

    For report files that are split over multiple files, only the first file has a report header record and only the last file has a report footer and a report record count record. A report with two sections split over two files might be organized as follows:

    File 1File 2
    Report Header (RH)File Header (FH)
    File Header (FH)Row Data (SB)
    Section Header (SH)...
    Column Header (CH)Row Data (SB)
    Row Data (SB)Section Footer (SF)
    ...Section Record Count (SC)
    Row Data (SB)Report Footer (RF)
    Section Footer (SF)Report Record Count (RC)
    Section Record Count (SC)File Footer (FF)
    Section Header (SH)
    Column Header (CH)
    Row Data (SB)
    ...
    File Footer (FF)

    Report data

    This section details the columns and related data that is delivered in the report header, report footer, and report record count records.

    NOTE: If the report is split over multiple files, only the last file contains the report footer and report record count records.

    Report header data

    Report header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.4 Report header data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"RH"
    2 Report Generation DateType: date/timeThe date and time when the report file was generated, in the following format: YYYY/MM/DD HH:MM:SS offset where:
    • YYYY is the four-digit year.
    • MM is two-digit month of the year.
    • DD is the two-digit day of the month.
    • HH is the hour in 24-hour notation.
    • MM is minutes.
    • SS is seconds.
    • offset is the five-character signed offset from GMT. For example, +0800.
    3Reporting WindowType: varcharThe window of time when the report was generated, as follows:
      X: GMT 00:00 to GMT -0500.
      A: GMT -0500 to GMT-0800.
      H: GMT-0800 to GMT +0800.
      R: GMT +0800 to GMT 00:00.
    4 Account IDType: varcharAccount number receiving the report (Payer ID – encrypted hash of PayPal account)
    5Report VersionType: varcharThe version of the report

    Report footer data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.5 Report footer data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"RF"
    2Row CountType: NumberThe number of body data rows in the report (used for reconciliation). Note that the report may span multiple files.

    Report record count data

    Report record count data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.6 Report record count data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"RC"
    2Row CountType: NumberThe number of body data rows in the report (used for reconciliation). Note that the report may span multiple files.

    File data

    This section details the columns and related data that is delivered in the file header and file footer records.

    NOTE: Each file in the report has a file header and a file footer, even if the number of files in the report is one.

    File header data

    File header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.7 Report file header data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"FH"
    2File CountType: NumberThe sequence number of the file in the report (used for reconciliation).

    File footer data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.8 File footer data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"FF"
    2Row CountType: NumberThe number of body data rows in the file (used for reconciliation).

    Section data

    This section details the columns and related data that is delivered in the section header, section footer, and section record count records.

    NOTE: If you are not using Multiple Account Management, the report contains only one section.

    Section header data

    All section header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.9 Section header data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"SH"
    2 Reporting Period Start DateType: date/timeThe date time that represents the beginning time period of the report in the following format:
      YYYY/MM/DD HH:MM:SS offset where:
    • YYYY is the four-digit year.
    • MM is two-digit month of the year.
    • DD is the two-digit day of the month.
    • HH is the hour in 24-hour notation.
    • MM is minutes.
    • SS is seconds.
    • offset is the five-character signed offset from GMT. For example, +0800.
    3Reporting Period End DateType: date/timeThe date time that represents the ending time period of the report in the following format:
      YYYY/MM/DD HH:MM:SS offset where:
  • YYYY is the four-digit year.
  • MM is two-digit month of the year.
  • DD is the two-digit day of the month.
  • HH is the hour in 24-hour notation.
  • MM is minutes.
  • SS is seconds.
  • offset is the five-character signed offset from GMT. For example, +0800.
  • 4Account IDType: varcharAccount number generated by PayPal

    Section body data

    Body data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    Before any rows of body data in the report, a column header row lists the name of each of the fields in each body data row. The column header column starts with CH, followed by the Column Name for each body data field (except for the "column type" field). For example:

    "CH","Subscription ID","Subscription Action Type","Subscription Currency","Subscription Creation Date","Subscription Period 1","Period 1 Amount","Subscription Period 2","Period 2 Amount","Subscription Period 3","Period 3 Amount","Recurring","Recurrence number","Subscription Payer PayPal Account ID","Subscription Payer email address","Subscription Payer Name","Subscription Payer Business Name","Shipping Address Line1","Shipping Address City","Shipping Address State","Shipping Address Zip","Shipping Address Country","Subscription Description","Subscription Memo","Subscription Custom Field"

    TABLE 1.10 Section body data

    Field NameData CharacteristicsDescription
    1.Column TypeType: Literal"SB"
    2.Subscription ID
      Type: Varchar
      Blanks: Yes
      Max Length: 24 characters
    Unique subscription agreement identification number.
    3.Subscription Action Type
      Type: Number
      Blanks: Yes
      Max Length: 5 characters
    One of the following values:
  • S0000: Subscription Created: general
  • S0100: Subscription Modification: general
  • S0200: Subscription Cancellation: general
  • S0300: Subscription End-of-Term
  • 4.Subscription Currency
      Type: Char
      Blanks: Yes
      Max Length: 3 characters
    Currency of transaction. [See PayPal supported currencies](paypal-supported-currencies) for possible values.
    5.Subscription Creation Date
      Type: Date
      Blanks: Yes
      Max Length: 25 characters
    Date and time the transaction was completed, in the following format:
      YYYY/MM/DD HH:MM:SS offset
      where:
      YYYY is the four-digit year.
      MM is two-digit month of the year
      DD is the two-digit day of the month.
      HH is the hour in 24-hour notation.
      MM is minutes.
      SS is seconds.
      offset is the five-character signed offset from GMT. For example, +0800.
    6. Subscription Period 1
      Type: alphanumeric
      Blanks: Yes
      Max Length: 3 characters
    Subscription period 1. This is the length of the first subscription period. Time unit values are: D (days), W (weeks), M (months), Y (years).
    7.Period 1 Amount
      Type: Number
      Blanks: Yes
      Max Length: 25 characters
    Subscription amount 1. This is the price of the first subscription period. A value of 0 indicates a free trial period.
    8. Subscription Period 2
      Type: alphanumeric
      Blanks: Yes
      Max Length: 3 characters
    Subscription period 2. This is the length of the second subscription period. Time unit values are: D (days), W (weeks), M (months), Y (years).
    9.Period 2 Amount
      Type: Number
      Blanks: Yes
      Max Length: 25 characters
    Subscription amount 2. This is the price of the second subscription period. A value of 0 indicates a free trial period.
    10.Subscription Period 3
      Type: alphanumeric
      Blanks: Yes
      Max Length: 3 characters
    Subscription period 3. This is the length of the third subscription period. Time unit values are: D (days), W (weeks), M (months), Y (years).
    11.Period 3 Amount
      Type: Number
      Blanks: Yes
      Max Length: 25 characters
    Subscription amount 3. This is the price of the third subscription period. A value of 0 indicates a free trial period.
    12.Recurring
      Type: numeric
      Blanks: Yes
      Max Length: 1 character
      Indicator that the subscription is a recurring payment:
      0 = no
      1 = yes
    13.Recurrence Number
      Type: numeric
      Blanks: Yes
      Max Length: 25 characters
    The number of times a payment will recur.
    14.Subscription Payer PayPal Account ID
      Type: Varchar
      Blanks: Yes
      Max Length: 24 characters
    Unique PayPal customer account number.
    15. Subscription Payer Email Address
      Type: Varchar
      Blanks: Yes
      Max Length: 127 characters
    Email address of payer
    16. Subscription Payer Name
      Type: varchar
      Blanks: Yes
      Max Length: 55 characters
      First and last name of subscription payer, in the following format:
      firstName lastName
    17. Subscription Payer Business Name
      Type: varchar
      Blanks: Yes
      Max Length: 127 characters
    Payer’s business name.
    18.Shipping Address Line 1
      Type: varchar
      Blanks: Yes
      Max Length: 300 characters
    Street address of shipping address as specified by buyer
    19. Shipping Address Line 2
      Type: text
      Blanks: Yes
      Max Length: 300 characters
    Street address of shipping address as specified by buyer
    20.Shipping Address City
      Type: text
      Blanks: Yes
      Max Length: 120 characters
    City of shipping address as specified by buyer
    21. Shipping Address State
      Type: text
      Blanks: Yes
      Max Length: 120 characters
    State, province, or territory of shipping address as specified by payer
    22.Shipping Address Zip
      Type: Varchar
      Blanks: Yes
      Max Length: 60 characters
    Postal code of shipping address as specified by payer
    23.Shipping Address Country
      Type: Varchar
      Blanks: Yes
      Max Length: 64 characters
    Country of shipping address as specified by payer
    24.Subscription Description
      Type: alphanumeric
      Blanks: Yes
      Max Length: 200 characters
    Description of the agreed as specified by the merchant
    25.Subscription Memo
      Type: varchar
      Blanks: Yes
      Max Length: 200 characters
    Text entered by payer in the Memo field during the enrollment
    26. Subscription Custom Field
      Type: varchar
      Blanks: Yes
      Max Length: 256 characters
    Custom content specified by originator of the agreement. Reserved for use by merchant.

    Section footer data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.11 Section footer data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"SF"
    2Row CountType: NumberThe number of body data rows in the section (used for reconciliation)

    Section record count data

    Section record count data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

    TABLE 1.12 Section record count data

    PositionColumn NameData TypeData Description
    1Column TypeType: Literal"SC"
    2Row CountType: NumberThe number of body data rows in the section (used for reconciliation)

    PayPal supported currencies

    CurrencyISO-4217 Code
    Australian DollarAUD
    Brazilian Real (This currency is supported as a payment currency and a currency balance for in-country accounts only.)BRL
    Canadian DollarCAD
    Czech KorunaCZK
    Danish KroneDKK
    EuroEUR
    Hong Kong DollarHKD
    Hungarian ForintHUF
    Israeli New SheqelILS
    Japanese YenJPY
    Malaysian Ringgit (This currency is supported as a payment currency and a currency balance for in-country accounts only.)MYR
    Mexican PesoMXN
    Norwegian KroneNOK
    New Zealand DollarNZD
    Philippine PesoPHP
    Polish ZlotyPLN
    Pound SterlingGBP
    Russian RubleRUB
    Singapore DollarSGD
    Swedish KronaSEK
    Swiss FrancCHF
    Taiwan New DollarTWD
    Thai BahtTHB
    Turkish LiraTRY
    U.S. DollarUSD

    Version history

    Publication DateVersionDescription
    September 20202.3Converted this report specification documentation from PDF to HTML.
    April 20192.2Updated the file record limit from 100,000 to 1 million.
    September 20152.1
  • Various content changes
  • October 20122.0.1
  • Changed the order so that Section Footer (SF) appears before Section Record Count (SC).
  • Changed the order so that Record Footer Data (RF) appears before Report Record Count Data (RC).
  • Updated sample report.
  • September 20122.0
  • Updated version to 2.0.
  • Changed file format to - SUB-yyyymmdd.sequenceNumber.version.format
  • Changed the order so that Report Record Count Data (RC) appears before Record Footer Data (RF).
  • Changed the order so that Section Record Count (SC) appears before Section Footer (SF).
  • Updated sample report.
  • August 20121.2.5Updated data descriptions for the following columns -
  • Period 1 Amount
  • Period 2 Amount
  • Period 3 Amount
  • Recurring
  • Recurrence Number
  • Subscription Action Type
  • Subscription Creation Date
  • Subscription Currency
  • Subscription ID
  • Subscription Payer Email Address
  • Shipping Address Country
  • Shipping Address Zip
  • April 20121.2.4 Updated max length of the following columns -
  • Shipping Address Line 1 - Max length 300 characters
  • Shipping Address Line 2 - Max length 300 characters
  • Shipping Address City - Max length 120 characters
  • Shipping Address State - Max length 120 characters
  • Shipping Address Zip - Max length 60 characters
  • Shipping Address Country - Max length 64 characters
  • October 2008 1.2.3
  • Updated information about report retention time on the Secure FTP Server.
  • Changed the Secure FTP server directory location from ppreports to ppreports/outgoing.
  • May 20071.2.2Updated to reflect new file and data structure
    October 20121.0.0First release of PayPal Merchant Subscription Agreement Report.

    See also