Skip to main content

Scheduled and Ad hoc

The Reporting API allows you to schedule and customize the frequency of your reports as per your needs.

Before you begin

Determine the integration option you want to use:

Entity

Entity defines the level of the merchant relationship as it relates to the acquiring account. Contact your relationship manager to know your entity IDs across different entity types. Determine the entity type you want to use in the report configuration from the following:

Entity types
Entity type Description
PE Processing Entity
TD Transaction Division 
FTI Fund Transfer Instruction
BU Business Unit
CO Company 
RGPE Reporting group for processing entity
RGTD Reporting group for transaction division
RGFTI Reporting group for fund transfer instruction
RGBU Reporting group for business unit
RGCO Reporting group for company

For more information on reporting groups, refer to reporting groups and how to manage reporting groups.

Note

A few things to keep in mind for FTI-level reports:

  • Reports generated using transactional or dispute details report types will have the reporting data aggregated for all the business units associated with the FTI.
    • For other report types, the reporting data will remain at the FTI-level.
  • You cannot create report configurations for multi-sectional FTI-level reports that include both transactional and non-transactional reporting data across different sections.

Scheduling reports

The Reporting API uses the standard UTC format for all times and timestamps.

You can also update the frequency on an existing report configuration at any time. The following fields are used for scheduling a report.

Required fields for scheduling a report
Field name Description Valid values
scheduleFrequency Specifies frequency of the report schedule. 
  • daily — Running a report every day.
  • weekly — Running a report every Tuesday would be weekly|tue.
  • monthly — Running a report on the 3rd day following the end of the month would be monthly|3.
  • adhoc — Running a report on a custom schedule.
reportFileScheduleTime Specifies when report generation should begin, not when the report has completed. Applies only for daily, weekly, and monthly.  Time in UTC time zone. 
reportingPeriodStartTime  Specifies the starting point for data collection. The start time must be your end of day time to include all information in that period for daily, weekly, and monthly.

Your end of the day time in UTC time zone. 

For example, if the your end of the day is 10 PM EST, the reportingPeriodStartTime is 03:00:00.
reportingPeriodEndTime Specifies the ending point for data collection. Applies only for ad hoc. Your end of the day time in UTC time zone.
Note

You can configure a maximum of 20 unique report configurations per entity ID using the Reporting API. 

Daily schedule

Schedule daily reports by setting scheduleFrequency to daily. You can control when the report runs and from when the data collection should begin using the fields reportFileScheduledTime and reportingPeriodStartTime.

The following table shows how the calculation works:

Scenarios for day calculation
Scenario Resulting day calculation
If the reportFileScheduledTime is greater than or equal to [reportingPeriodStartTime + 4 hours] The report will contain data from T-1 (the previous day) through T (current day).
If the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours] The report will contain data from T-2 (2 days back) through T-1 (previous day).

The following table shows an example of how the calculation works:

Examples of daily schedule
Merchant end of day time reportingPeriodStartTime reportFileScheduledTime Report generation date Reporting data
3 AM UTC 3 AM UTC 12 PM UTC 9-Sep From 8th Sept 3 AM to 9th Sept 3 AM
3 AM UTC 3 AM UTC 6 AM UTC 9-Sep From 7th Sept 2 AM to 8th Sept 3 AM

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is greater than [reportingPeriodStartTime + 4 hours].

HTTP method: POST

Endpoint: /reports

Scenario 1: Schedule a report that runs every day at 12:00:00 UTC (T) and includes 24 hours of data from yesterday at 03:00:00 UTC (T-1) until today at 02:59:59 (T).

Json
{  
     "frequencyConfig": { 
            "scheduleFrequency": "daily", 
            "reportFileScheduledTime": "12:00:00", 
            "reportingPeriodStartTime": "03:00:00" 
       }
}

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours]. The ability to define custom time intervals this way accommodates for varying end-of-day funding cycles across global operations.

Scenario 2: Schedule a report that runs every day at 06:00:00 UTC (T) and includes 24 hours of data from the day before yesterday at 03:00:00 UTC (T-2) until yesterday at 02:59:59 (T-1).

Json
{  
     "frequencyConfig": { 
          "scheduleFrequency": "daily", 
          "reportFileScheduledTime": "06:00:00", 
          "reportingPeriodStartTime": "03:00:00" 
      }
}

Weekly schedule

Schedule weekly reports by setting scheduleFrequency to weekly|(day of the week). You can:

  • Specify the day of the week when the report should be generated.
  • Control the time when the report runs using the field reportFileScheduledTime.
  • Control when the data collection should begin using the field reportingPeriodStartTime.

The following table shows how the calculation works:

Scenarios for day calculation for weekly schedule
Scenario Resulting day calculation
If the reportFileScheduledTime is greater than or equal to [reportingPeriodStartTime + 4 hours] The report will contain data from T-7 (days) through T (current day).
If the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours] The report will contain data from T-8 (days) through T-1 (previous day).

The following table shows examples of how the calculation works:

Examples of weekly schedule
Merchant end of day time reportingPeriodStartTime reportFileScheduledTime Report generation date Reporting data
3 AM UTC 3 AM UTC 12 PM UTC 9-Sep From 2nd Sept 3 AM to 9th Sept 3 AM
3 AM UTC 3 AM UTC 6 AM UTC 9-Sep From 1st Sept 3 AM to 8th Sept 3 AM

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is greater than [reportingPeriodStartTime + 4 hours].

HTTP method: POST

Endpoint: /reports

Scenario 1: A report that runs every Tuesday at 12:00:00 UTC and includes 7 days of data timestamped between a week ago from Monday (T-7) at 03:00:00 UTC to Monday (T) at 02:59:59 UTC.

Json
{  
     "frequencyConfig": {   
          "scheduleFrequency": "weekly|tue",  
          "reportFileScheduledTime": "12:00:00",  
          "reportingPeriodStartTime": "3:00:00"  
      }
}

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours]. 

Scenario 2: A report that runs every Monday at 06:00:00 UTC and includes 7 days of data timestamped between a week ago from Sunday (T-8) at 03:00:00 UTC to Sunday (T-1) at 02:59:59 UTC.

Json
{  
     "frequencyConfig": {   
          "scheduleFrequency": "weekly|mon",  
          "reportFileScheduledTime": "06:00:00",  
          "reportingPeriodStartTime": "03:00:00",  
      }
}

Monthly schedule

Schedule monthly reports by setting scheduleFrequency to monthly|(day of the month). You can:

  • Specify the day of the month when the report should be generated. This cannot be greater than 28, meaning a report cannot be scheduled to run on the 29th day of every month.
  • Control the time when the report runs using the field reportFileScheduledTime.
  • Control when the data collection should begin using the field reportingPeriodStartTime.

The following table shows how the calculation works:

Scenarios for day calculation for monthly schedule
Report generation date Scenario Resulting day calculation
 First day of the month (monthly|1) If the reportFileScheduledTime is greater than or equal to [reportingPeriodStartTime + 4 hours] The report will contain data from the first day of the previous month through to the first day of the current month.
If the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours] The report will contain data from the first day of the previous month through the last day of the previous month.
Any other day apart from the first day of the month If the reportFileScheduledTime is greater than or equal to [reportingPeriodStartTime + 4 hours] The report will contain data from the first day of the previous month through to the first day of the current month.
If the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours]

The following table shows examples of how the calculation works:

Examples of monthly schedule
Merchant end of day time reportingPeriodStartTime reportFileScheduledTime Report generation date Reporting data
3 AM UTC 3 AM UTC 12 PM UTC 1-Sep (monthly|1) From 1st Aug 3 AM to 1st Sep 3 AM
3 AM UTC 3 AM UTC 6 AM UTC 1-Sep (monthly|1) From 1st Aug 3 AM to 31st Aug 3 AM
3 AM UTC 3 AM UTC 12 PM UTC 2-Sep (monthly|2) From 1st Aug 3 AM to 1st Sep 3 AM
3 AM UTC 3 AM UTC 6 AM UTC 2-Sep (monthly|2) From 1st Aug 3 AM to 1st Sep 3 AM

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is greater than [reportingPeriodStartTime + 4 hours] and the report generation date is the first day of the month (monthly|1).

HTTP method: POST

Endpoint: /reports

Scenario 1: A report that runs on the first day at 12:00:00 UTC following the end of each month and reports a full UTC month from the first day of the previous month (1st Aug) at 03:00:00 UTC through the first day of the current month (1st Sep) at 02:59:59 UTC.

Json
{  
     "frequencyConfig": {  
         "scheduleFrequency": "monthly|1",  
         "reportFileScheduledTime": "12:00:00",  
         "reportingPeriodStartTime": "03:00:00"  
      }
}

The following frequencyConfig code sample shows a scenario where the reportFileScheduledTime is less than [reportingPeriodStartTime + 4 hours] and the report generation date is the first day of the month (monthly|1). 

Scenario 2: A report that runs on the first day at 06:00:00 UTC following the end of each month and reports a full month from the first day of the previous month (1st Aug) at 03:00:00 UTC through the last day of the previous month (31st Aug) at 02:59:59 UTC.

Json
{  
     "frequencyConfig": {  
           "scheduleFrequency": "monthly|1",  
           "reportFileScheduledTime": "06:00:00",  
           "reportingPeriodStartTime": "03:00:00",  
       }
}

Ad hoc

Ad hoc is used to run scheduled reports on custom date ranges instead of daily, weekly, or monthly by setting scheduleFrequency to adhoc.

The following table shows examples of how the calculation works.

Examples of ad hoc report configurations
Merchant end of day time reportingPeriodStartTimestamp reportingPeriodEndTimestamp Report generation date Reporting data
3 AM UTC 2nd Sept - 3 AM UTC 9th Sept - 3 AM UTC 9-Sep From 2nd Sept 3 AM to 9th Sept 3 AM

For example, the below ad hoc report will include data from 2nd September to 9th September:

HTTP method: POST

Endpoint: /reports

Json
{
     "frequencyConfig": {  
          "scheduleFrequency": "adhoc",  
          "reportingPeriodStartTimestamp": "2024-09-02 03:00:00",  
          "reportingPeriodEndTimestamp": "2024-09-09 02:59:59"  
     }
}

At any point, you can change the ad hoc frequency configuration when triggering the report to run. This does not require updating the report configuration first.

Note

You can generate adhoc reports for the last 6 months of data from the current date.

Handling daylight saving time

Reporting handles daylight saving time (DST) differently for scheduled and ad hoc reports.

  • Scheduled Reports (Daily/Weekly/Monthly): Our system automatically adjusts for Daylight Saving Time when generating scheduled reports. This means you can rely on the system to deliver your reports at the expected times without any additional action required on your part.
  • Ad hoc Reports: You need to manually convert timestamps to UTC. This ensures that the data you receive accurately reflects the intended time period, taking into account any DST changes. We recommend verifying the time adjustments during the DST transition periods to ensure the accuracy of your ad hoc reports.

Examples

The following examples will help you better understand how to handle DST in ad hoc reports.

During DST (March to November)

Let’s say your Merchant End of Day (MEOD) is set to 10 PM EST during DST, then you must update your reportingPeriodStartTimestamp to 3 AM UTC during DST.

HTTP method: PUT

Endpoint: /report-configs/{report-configuration-id}

Scenario: Scheduling an ad hoc monthly report for April.

codeblock-dst-1
Json
{
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2024-04-01 03:00:00",
        "reportingPeriodEndTimestamp": "2024-05-01 02:59:59"
    }
}

After Daylight Saving Time (November to March)

Let’s say your Merchant End of Day (MEOD) is set to 10 PM EST after DST, then you must update your reportingPeriodStartTimestamp to 2 AM UTC (standard time) after DST.

HTTP method: PUT

Endpoint: /report-configs/{report-configuration-id}

Scenario: Scheduling an ad hoc monthly report for December.

codeblock-dst-2
Json
{
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2024-12-01 02:00:00",
        "reportingPeriodEndTimestamp": "2025-01-01 01:59:59"
    }
}

Transition from Standard Time to DST (March)

Let's say your Merchant End of Day (MEOD) is 10 PM EST during March, then you must update your reportingPeriodEndTimestamp from 2 AM UTC (standard time) to 3 AM UTC (DST).

HTTP method: PUT

Endpoint: /report-configs/{report-configuration-id}

Scenario: Scheduling an ad hoc monthly report for March.

codeblock-dst-4
Json
{
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2024-03-01 02:00:00",
        "reportingPeriodEndTimestamp": "2024-04-01 02:59:59"
    }
}

Transition from DST to Standard Time (November)

Let's say your Merchant End of Day (MEOD) is 10 PM EST during November, then you must update your reportingPeriodEndTimestamp from 3 AM UTC (DST) to 2 AM UTC (standard time).

HTTP method: PUT

Endpoint: /report-configs/{report-configuration-id}

Scenario: Scheduling an ad hoc monthly report for November.

codeblock-dst-3
Json
{
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2024-11-01 03:00:00",
        "reportingPeriodEndTimestamp": "2024-12-01 01:59:59"
    }
}

Key Considerations

  • DST Transition: Pay special attention to the transition periods in March and November, as the conversion between local time (EST) and UTC changes.
  • Consistency: Ensure that the timestamps you provide for ad hoc reports are consistent with the DST status during the reporting period.

By following these guidelines and examples, you can ensure that your reports accurately reflect the intended time periods, whether DST is in effect or not.

Get a report configuration  
Get report configuration details  
Update a report configuration  
Set up a report schedule  
Create advanced customizations