Returning.AIDevelopers
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 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/bulk-update-premium-currency
Permission
bulkUpdateUser
Retries
No Idempotency-Key; check API 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
bulkUpdateUserShown in the dashboard as “Bulk Update User”

Uploading needs bulkUpdateUser, shown in the dashboard as Bulk Update User, the same permission as Bulk update users from CSV. 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. It ends as completed, even when some rows failed, or as failed when the file as a whole was rejected. The API can't read these jobs: they aren't in List bulk update jobs, and the upload returns no job ID. Follow the job in the dashboard under Settings > Integration > API Logs. A finished job records how many rows succeeded and failed; a failed job records why the file was rejected.

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.

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 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 so you can find the job in 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 API 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 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 lacks bulkUpdateUser, or it is a personal key. Use a Community API key and add the permission 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.
{
  "status": "fail",
  "message": "Uploaded file must be a CSV"
}

Next step#

Bulk update users from CSVPOST/v1/users/bulk-updateUse the user CSV upload for coins, XP, roles or custom fields in the same run.