Get loyalty points export download link

When to use this

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

customerSuccessShown in the dashboard as Customer Success.

Use a Community API key with customerSuccess, shown as Customer Success in the dashboard. Keep the key on your backend and send Authorization: Bearer <API_KEY>. The key selects the community; do not send a community ID. Personal API keys are not supported.

All three calls use https://api.returning.ai and return Cache-Control: no-store. They accept no query parameters. A valid community key with the required permission can read that community's export jobs, including jobs created by another key in the same community.

Successful responses contain meta, message and data. Read job state from data.status. An HTTP 200 means the status request succeeded, even when the job is failed. Errors put their machine-readable code in meta.code; do not branch on message.

02Behaviour#

curl --fail --output points.csv '<TEMPORARY_DOWNLOAD_URL>'

03Request#

Path parameters#

Headers#

curl --request GET \
  --url https://api.returning.ai/v1/loyalty-exports/66f000000000000000000701/download \
  --header 'Authorization: Bearer <API_KEY>'

04Response#

Download the file with a plain HTTPS GET. Check Create loyalty points export for CSV columns, JSON fields and daily-load guidance.

Verify and store the file

Compare the downloaded byte length with file_size_bytes from the completed status. For CSV, parse it with a CSV library and count data records, excluding the header; fields can be quoted, so counting newline characters is not a reliable row count. For JSON, count objects in the array. Compare that count with total_rows.

Store the file only after the transfer and parsing checks succeed. Keep customer data private and apply your own retention policy. The API's 24-hour availability is a download window, not a retention policy for files you have saved yourself.

Two different expiry times

A file-host HTTP 403 may mean the temporary URL expired or was copied incompletely. Get a fresh link and copy it exactly. If a fresh link also fails, stop retrying it repeatedly and contact support with the export ID and API request ID. Do not send support the API key, signed URL or raw customer file.

The file host's errors are not the API's JSON error envelope. Use the status and download-link endpoints to distinguish an unfinished job, an expired artifact and a temporary download failure.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "requestId": "example-request"
  },
  "message": "Loyalty export download success.",
  "data": {
    "filename": "points-1788397200000.csv",
    "url": "https://download.example.com/temporary-file",
    "url_expires_at": "2026-09-03T01:07:00.000Z"
  }
}

05Errors#

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_ERROR",
    "requestId": "req_example"
  },
  "message": "Loyalty export request error.",
  "detail": "Invalid request or unsupported query parameters."
}

06Next step#