The Export API allows you to obtain bulk payment and order data from merchants who have installed your app. This service is not real-time, so your chance of running into API limit restrictions is lower. Consider using this service for data collection if you need merchant orders and payment histories.

📘

NOTE

If you have not used this endpoint before, email [email protected] during your app review to inquire about permissions.

Prerequisites

Install and set up the following before using the Export API:

• Python 3.7.3 (backward compatible with 2.7)
• pip Python package manager
• Clover sandbox developer account

Usage considerations

Consider the following points before using the Export API:

• Availability time:
  • United States (US) UTC: MON-FRI 10:00-15:00, SAT 10:00-15:00, SUN 10:00-15:00
  • Europe UTC: MON-FRI 01:00-05:00, SAT 02:00-05:00, SUN 02:00-06:00
• Sandbox is not limited to specific times.
• Returns 1000 objects per file. If your response contains more than 1000 objects, returns an array of files to capture.
• Deletes exported files after 24 hours.
• Maximum time range is 30 days. If your data spans are longer, break the request into multiple requests.
• Server handles a few exports concurrently. Wait for each export to finish before you start another one. The server returns 503 errors whenever the threshold is reached.

Use the endpoint

Step 1: Create the request

Make a POST call to /v3/merchants/{merchant_Id}/exports with the appropriate payload:

• export_type (PAYMENTS or ORDERS)
• start_time (In UTC)
• end_time (in UTC)

{
      "type": export_type,
      "startTime": start_time,
      "endTime": end_time
  }

The exports object response includes the export id for you to use in the next step.

Step 2: Check the status and percent complete periodically

Using the export id from the previous step, make a GET call to /v3/merchants/{merchant_Id}/exports/{export_Id}

The following status may appear:

• PENDING—In the queue to be processed.
• IN_PROGRESS—Being processed
• DONE—Process complete

{
  "status": "PENDING",
  "modifiedTime": modified_time,
  "merchantRef": {
    "id": "merchant_id"
  },
  "percentComplete": 0,
  "startTime": start_time,
  "createdTime": created_time,
  "endTime": end_time,
  "type": "ORDERS",
  "id": "export_id"
}

Step 3: Download the exported files

After the request completes, your export object includes URLs (links) to the exported files for you to download.

{
  "id": "export_id",
  "type": "ORDERS",
  "status": "DONE",
  "percentComplete": 100,
  "availableUntil": available_until_time,
  "startTime": start_time,
  "endTime": end_time,
  "createdTime": created_time,
  "modifiedTime": modified_time,
  "exportUrls": {
    "elements": [
      {
        "url": URL,
        "export": {
          "id": "export_id"
        }
      }
    ]
  },
  "merchantRef": {
    "id": "merchant_id"
  }
}