Create loyalty points export

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#

python3 export-loyalty-points.py \
  --start '2026-09-01T00:00:00.000Z' \
  --end '2026-09-02T00:00:00.000Z' \
  --state export-2026-09-01.state.json \
  --out points-2026-09-01.csv

curl --fail-with-body \
  'https://api.returning.ai/v1/loyalty-exports/66f000000000000000000701' \
  --header 'Authorization: Bearer <API_KEY>'

curl --fail-with-body \
  'https://api.returning.ai/v1/loyalty-exports/66f000000000000000000701/download' \
  --header 'Authorization: Bearer <API_KEY>'


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

03Request#

Headers#

Body#

The body must be JSON and at most 1 MiB. Unknown body fields are rejected. An empty client_refs array is invalid; it does not mean all customers.

To select customers and request JSON, use:

{
  "dataset": "points_transactions",
  "format": "json",
  "start_at": "2026-09-01T00:00:00.000Z",
  "end_at": "2026-09-02T00:00:00.000Z",
  "client_refs": ["000101", "000102"]
}

References use your community's active customer identifier. Do not assume this is the Returning.AI user ID. Text identifiers preserve case, spaces and leading zeroes. Numeric identifiers use canonical numeric text: 000101 does not match a numeric identifier stored as 101.

Selection is resolved during processing. An unknown or ambiguous selected identifier fails the job rather than returning a partial selection. Without a selection, unresolved identifiers can appear as null in JSON or blank in CSV. Identifier values are resolved when the report runs, not as they were at the historical event time.

curl --request POST \
  --url https://api.returning.ai/v1/loyalty-exports \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: 9b629318-5c67-4799-8135-27a64f1fc529' \
  --header 'Content-Type: application/json' \
  --data '{
    "dataset": "points_transactions",
    "format": "csv",
    "start_at": "2026-09-01T00:00:00.000Z",
    "end_at": "2026-09-02T00:00:00.000Z"
  }'

04Response#

New jobs return 202. An exact replay returns 200 with the original job's current state. Save data.export_id; acceptance does not mean the file is ready. There is no success meta.code or returned polling interval.

File contents and daily loads

CSV is UTF-8 with these five columns, in this order:

Ordinary zero-movement rows are excluded. An overwrite that sets the balance to zero is retained. Do not sum every points_delta as points earned: handle overwrites separately and treat unknown values as unknown, not zero.

Rows are newest first by recording time, with a stable identifier tie-breaker. The date interval is inclusive at start_at and exclusive at end_at.

JSON is an array, not JSONL. It includes the five CSV fields plus schema_version, community_id, returning_user_id, occurred_at_utc, currency_type, absolute_balance, raw_action, source_reference and quality_notes. schema_version is 1, currency_type is reward, and occurred_at_utc is null. absolute_balance is populated for overwrites. raw_action is JSON-encoded text, while quality_notes is an array of strings. Extra JSON fields may contain personal data; protect the whole file.

source_reference is not necessarily a trade or order ID. operation does not reliably classify trade, mission or redemption reasons. Quality notes identify uncertainties such as missing identifiers or original activity times.

CSV text that could be interpreted as a spreadsheet formula receives a leading apostrophe; signed amounts do not. Use JSON when your automated import needs original text without spreadsheet escaping.

Example CSV records

These illustrative records show the five-column layout. Real event_id values are opaque strings; keep them exactly as received. The rows are ordered newest first.

client_ref,event_id,recorded_at_utc,operation,points_delta
000101,<eventId-3>,2026-09-01T14:00:00.000Z,overwrite,40
000101,<eventId-2>,2026-09-01T13:00:00.000Z,decrease,-10
000101,<eventId-1>,2026-09-01T12:00:00.000Z,increase,25

For an empty CSV, only the header line is present. For empty JSON, the file contains [].

JSON field reference

JSON is useful when you need extra context or original identifier text without CSV spreadsheet escaping. It is a single array of objects. Read numeric amounts as numeric text and preserve identifier strings; avoid converting client_ref to a number.

Amounts use the source's native numeric precision and may appear in scientific notation. A string does not imply arbitrary-precision accounting. A missing or invalid amount becomes null in JSON or blank in CSV; do not silently turn it into zero.

Interpreting points correctly

For increase and decrease, keep the amount's sign. Do not make every amount positive. For overwrite, the amount assigns a balance and cannot be added to earned points.

For example, if a balance was 100 and an overwrite assigns 40, a row with operation: "overwrite" and points_delta: "40" does not mean the trader earned 40. You cannot calculate its -60 effect from that row alone unless you have a trustworthy prior balance. In JSON, absolute_balance also contains "40".

expiry is distinguished from ordinary decreases. unknown means the amount or classification is not known well enough; retain it for review. No operation value reliably tells you whether the business reason was trading, a mission or a store purchase.

Treat quality notes as an extensible list: retain unrecognized notes instead of rejecting the whole file.

Daily loads

Request consecutive UTC recording-time windows. Use event_id to avoid duplicate rows when intentionally repeating or overlapping windows. A new request rereads history; an idempotent replay returns the same job.

The export is not a transactional snapshot or a guaranteed change feed. Late records and historical edits can make a fresh export differ. Deleted historical events are not supplied as deletion records. coverage: observed_history_only means recorded history, not certified financial completeness. The export does not reconstruct every historical balance.

For current balance summaries, use Get loyalty overview. For order details and fulfilment state, use List redemption orders by community.

Make a daily import reliable

1. Choose the closed recording-time window and persist the request body, API key identity, idempotency key and eventual export ID in your own job record.
2. Run only one active export for the community. On an uncertain create response, retry exactly; do not advance to the next window.
3. After completion, download the file promptly, check its row count and byte size, and store it privately. A byte-size check detects an incomplete transfer; the API does not supply a cryptographic checksum.
4. Upsert by event_id in your reporting store. Preserve client_ref as text, retain null/unknown values and quality notes, and handle overwrite rows separately.
5. Advance your own import checkpoint only after the entire file has been imported successfully. If an import partially fails, reuse the saved file or download it again while available, and repeat the upsert.
6. If your business needs reconciliation, deliberately re-export overlapping closed windows with new idempotency keys and deduplicate by event_id. Choose the overlap from your own source delays; the API does not promise a maximum lateness interval or a deletion feed.

This avoids checking each event against your database before requesting the API: the date filter selects the period and your import's upsert handles replayed rows. It does not add date filtering to the separate store-orders API.

Common questions

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

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#