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