API reference / Gamification / Loyalty Points

Get loyalty points export status

Check whether an export has completed and read its row count and file size.

Last updated 12 Oct 2026API v1

Method: GET
Path: https://api.returning.ai/v1/loyalty-exports/{exportId}
Permission: customerSuccess
Retries: Read-only; poll with a growing delay.

When to use this

Poll after requesting an export.
Check whether a failed or expired report needs a new request.

Authentication#

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.

Behaviour#

`data.status`	What to do
`queued`	Wait for processing.
`processing`	Continue polling with backoff.
`completed`	Read `total_rows` and `file_size_bytes`, then request a download link.
`failed`	Read `data.error`. Contact support or correct the cause before deliberately creating another job.
`cancelled`	No file is available. There is no public cancellation endpoint in this family.
`expired`	Create a new export if you still need the file.

Polling and recovery

Poll one known ID with increasing delays rather than creating another export. A client may choose a time budget and resume later using the saved ID. Reaching your own time budget does not cancel the job.

Situation	Action
Still `queued` or `processing`	Wait and poll with backoff. If unusually long, contact support with the export ID and `meta.requestId`.
HTTP 200 with `failed`	The status lookup succeeded, but the export failed. Read `data.error`; investigate the input or contact support before deliberately requesting a new job.
`cancelled`	Stop polling; this family provides no public cancel or restart operation.
`expired`	Start a deliberately new export if the file is still needed. Replaying the original create does not refresh it.
HTTP 404	Check the saved ID and the key's community. A malformed ID and an inaccessible ID both use `EXPORT_NOT_FOUND`.
HTTP 401 or 403	Correct the Community API key or its Customer Success permission before retrying.
Network error or HTTP 5xx	Retry the same GET with backoff. Do not create a replacement export merely because a status read failed.

Request#

Path parameters#

exportId#stringREQUIRED

Export ID returned by Create loyalty points export.

Rule24 hex characters

Eg66f000000000000000000701

Headers#

Authorization#stringREQUIRED

Community API key with Customer Success permission. The key selects the community.

RuleBearer <API_KEY>

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

Response#

export_id, status, dataset, format, created_at and coverage are always present. Only completed jobs include total_rows and file_size_bytes. A failed job adds error: {"code":"EXPORT_FAILED","message":"The export could not be completed."}. Other states omit these optional fields.

A completed empty export has total_rows: 0, a header-only CSV or an empty JSON array. It is not a list of customers with zero balances. No progress percentage, checksum, expiry timestamp, original filters or detailed failure reason is returned by this status endpoint.

Unknown IDs, malformed IDs and exports outside the authenticated community return 404 EXPORT_NOT_FOUND. Failed and expired jobs that still exist return HTTP 200 with their job state.

meta#objectALWAYS

Request result and support reference.

Eg{ ... }

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

HTTP status of the request.

Eg200

requestId#stringALWAYS

Support reference for this request.

Eg"example-request"

message#stringALWAYS

Human-readable summary. Do not branch on it.

Eg"Loyalty export status success."

data#objectALWAYS

Export job details.

Eg{ ... }

export_id#stringALWAYS

Save this ID for status and download requests.

Eg"66f000000000000000000701"

status#stringALWAYS

Current job state. Acceptance does not mean the file is ready.

Rulequeued, processing, completed, failed, cancelled or expired

Eg"completed"

dataset#stringALWAYS

The dataset requested.

Rulepoints_transactions

format#stringALWAYS

The requested file format.

Rulecsv or json

Eg"csv"

created_at#stringALWAYS

Job creation timestamp in UTC.

Eg"2026-09-03T01:00:00.000Z"

coverage#stringALWAYS

Recorded history only, not certified financial completeness.

Ruleobserved_history_only

total_rows#integerCOMPLETED ONLY

File row count; zero for an empty report. Present only when completed.

Eg4

file_size_bytes#integerCOMPLETED ONLY

File size in bytes. Present only when completed.

Eg640

error#objectFAILED ONLY

Generic failure details. Present only for a failed job.

code#string

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "requestId": "example-request"
  },
  "message": "Loyalty export status success.",
  "data": {
    "export_id": "66f000000000000000000701",
    "status": "completed",
    "dataset": "points_transactions",
    "format": "csv",
    "created_at": "2026-09-03T01:00:00.000Z",
    "coverage": "observed_history_only",
    "total_rows": 4,
    "file_size_bytes": 640
  }
}

Errors#

Fix the request07

400VALIDATION_ERRORFix the request

Remove unsupported query parameters and correct the request fields.

401AUTHENTICATION_REQUIREDFix the request

Send a valid Community API key in Authorization: Bearer <API_KEY>.

403API_KEY_PERMISSION_DENIEDFix the request

Use a Community API key with Customer Success permission.

403COMMUNITY_ACCESS_DENIEDFix the request

Use a Community API key, not a personal API key.

400Fix the request

Invalid request or unsupported query parameters.

401Fix the request

Missing or invalid API key.

403Fix the request

A Community API key with the required permission is needed.

Fix the data03

404COMMUNITY_NOT_FOUNDFix the data

Contact support about the community selected by your API key.

404EXPORT_NOT_FOUNDFix the data

Check the export ID and the community selected by your API key.

404Fix the data

The export was not found.

Retry with backoff03

503EXPORTS_UNAVAILABLERetry with backoff

Retry with backoff. For create, preserve the original body and idempotency key.

500AUTHENTICATION_FAILEDRetry with backoff

Retry with backoff; contact support if authentication checks keep failing.

503Retry with backoff

Exports disabled or unavailable. Retry creation with the same idempotency key.

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

Next step#

Get loyalty points export download linkGET/v1/loyalty-exports/{exportId}/downloadFor completed jobs, request a temporary download link.

Create loyalty points export

Get loyalty points export status

When to use this

01Authentication#

02Behaviour#

Polling and recovery

03Request#