Returning.AIDocs
v1

API reference / Bulk Operations

.md

Bulk update premium currency from CSV

Upload a CSV that adds to, subtracts from or sets many traders' premium currency balances in one background job.

Last updated 28 Oct 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/bulk-update-premium-currency
Permission
bulkUpdatePremiumCurrency
Retries
Not idempotent; check community logs before retrying

When to use this

  • A monthly campaign on your platform awards premium currency to a list of traders.
  • You correct premium currency balances for several traders after a support review.
  • You move premium currency balances over from another system when you launch.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
bulkUpdatePremiumCurrencyShown in the dashboard as “Bulk Update Premium Currency”. Keys with “Bulk Update User” are also accepted.

Uploading needs bulkUpdatePremiumCurrency, shown in the dashboard as Bulk Update Premium Currency. Keys with bulkUpdateUser (Bulk Update User), the permission for Bulk update users from CSV, are also accepted, but give new keys the premium currency permission. Every row is limited to traders in the key's community. Keep the key on your server.

Behaviour#

The upload only queues a job. Queued premium currency jobs run one at a time, oldest first. The job reads the whole file, checks every row, then applies the valid rows. These jobs aren't in List bulk update jobs, and the upload returns no job ID. Follow the job with Retrieve and export community logs: read logType=api records from the time of your upload, and find the one whose name is your log_name (Bulk Update Premium Currency when you sent none). It needs a key with readCommunityLogs. The same jobs are in the dashboard under Settings > Integration > API Logs.

  • Queued or In progress: the job hasn't finished.
  • Complete: the job finished. It is Complete even when some rows failed; error then gives the count, such as 1 user failed, and is empty when every row applied.
  • Error: the file as a whole was rejected and nothing was applied. error gives the reason.

The file as a whole is rejected, and nothing is applied, when Email or Premium Currency is missing from the header row, or the header row has any other column. A file with no data rows completes with nothing applied.

A row fails on its own, and the other rows still apply, when:

  • Email is empty, or the same email appears in an earlier row. Only the first row for each email is used.
  • Premium Currency is empty or not a number.
  • Premium Currency_op isn't add, subtract or overwrite.
  • No trader in your community has that email.

Which rows failed, and why, is shown only in the dashboard. Premium currency changes don't appear in the total_coins field history, and the API has no read for a trader's premium currency balance.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with bulkUpdatePremiumCurrency or bulkUpdateUser.

RuleBearer <API_KEY>

Body#

Send multipart/form-data with the file in field data, and optionally log_name. Columns are separated by commas, and the first line must be the header row.

CSV
Email,Premium Currency,Premium Currency_op
trader@example.com,500,add
  • Spell the headers exactly: Email, Premium Currency and, optionally, Premium Currency_op.
  • Rows are matched by Email, not case-sensitive.
  • add adds the amount and is the default when the operator column or cell is empty. subtract takes it away but never goes below 0. overwrite sets the balance to the amount.
  • The file can be up to 30 MB.
data#fileREQUIRED
The CSV file, with a header row and one row per trader. The form field must be named data.

Rule.csv name or text/csv type; max 30 MB

Eg"premium-currency.csv"

log_name#stringOPTIONAL
A name for this job. Make it unique; it is the job's name in community logs and API Logs.

Eg"Premium top-up 2026-09-27"

Send the body as multipart/form-data.

curl --request POST \
  --url https://api.returning.ai/v1/users/bulk-update-premium-currency \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'data=@premium-currency.csv' \
  --form 'log_name=Premium top-up 2026-09-27'

Response#

A 200 returns only a confirmation that the job is queued. It has no job ID, so use a unique log_name and look for it in community logs.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Bulk update premium currency process is queued"

data#objectALWAYS
A short confirmation.

Eg{ ... }

message#stringALWAYS
Human-readable confirmation that the job is queued.

Eg"Bulk update premium currency process is queued. You can check in Api Log ( community settings )"

{
  "status": "success",
  "message": "Bulk update premium currency process is queued",
  "data": {
    "message": "Bulk update premium currency process is queued. You can check in Api Log ( community settings )"
  }
}

Errors#

Errors from the API key check, such as 401 and 403, carry the code in meta.code. Other errors from this endpoint have no code, so branch on the HTTP status. Problems inside the file never cause an error here; they show up in the job's result in community logs and API Logs.

Fix the request03

400Fix the request

There is no code, so read message:

  • A CSV file must be provided: no file arrived. JSON bodies aren't accepted; send the file as multipart form field data.
  • Uploaded file must be a CSV: give the file a .csv name or a text/csv type.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current key.
403API_KEY_PERMISSION_DENIEDFix the request
The key is valid but has neither bulkUpdatePremiumCurrency nor bulkUpdateUser, or it is a personal key. Use a Community API key and add Bulk Update Premium Currency in Settings > Integration > API Keys.

Fix the data01

404COMMUNITY_NOT_FOUNDFix the data
The key's community no longer exists. Use a key from an active community.

Retry with backoff02

500Retry with backoff
A JSON 500 means no job was created; retry with backoff. A 500 error page without JSON means the file is over 30 MB or was sent under a form field other than data; fix the upload instead.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry the same request with backoff.

Retries

This endpoint is not idempotent, and it ignores an Idempotency-Key header. Each upload creates a new job, and running the same file twice applies add and subtract twice. After a timeout, look for your log_name in community logs before you upload again. Over the rate limit, requests return 429; wait for the window to reset, then retry.

{
  "status": "fail",
  "message": "Uploaded file must be a CSV"
}

Next step#

Follow the job with Retrieve and export community logsGET/v1/community-logsRead logType=api records for today and find the one whose name is your log_name.