Export merchant data

United States
Canada
Europe
Latin America

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"
  }
}