Export merchant data

United States
Canada
Europe

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. If you need merchant order and payment histories, then consider using this service for your data collection needs.

📘

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 (backwards 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:
  • US UTC: MON-FRI 10:00-15:00, SAT 10:00-15:00, SUN 10:00-15:00
  • EU 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, an array of files to capture is returned.
  • Deletes exported files after 24 hours.
  • The maximum time range is 30 days. If your data spans are longer than that, break the request into multiple requests.
  • The 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 appear:

  • PENDING - In 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 will include URLs 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"
  }
}