1. Bulk Operations
Returning.AI
  • Getting Started
  • Users
    • User directory and provisioning
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
    • Update User XP and Currency
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
      GET
    • Send Message
      POST
    • Reply Message
      POST
    • React Message
      POST
    • Upload message images
      POST
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
      • Get Daily Calculation Data
      • Get Rolling Calculation Data
    • Match Predictions
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Rewards & Redemptions
    • Store catalog to redemptions
    • Update redemption order status or refund
    • List redemption orders by user email
    • List redemption statuses
    • Get redemption status by ID
    • List redemption orders by community
    • Create redemption order status
    • Get redemption order status history
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
      GET
    • Get bulk update job status
      GET
    • Get bulk update job details
      GET
    • Bulk update users from CSV
      POST
    • Bulk update premium currency from CSV
      POST
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Store
    • Store catalog
    • Purchase History
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Update products in bulk
      • Create products in bulk
      • Create product with vouchers
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User field definitions and history
    • User Field History
      • Get all user field histories in a community
      • Get user field histories for a specific field
      • Get user field histories for a specific user
      • Get user field histories of specific user field and user
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Get A User Field Definition
    • Update A User Field Definition
    • Create A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Secure Auth
      • Register user with password
      • Verify user email
      • Log in user with password
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  1. Bulk Operations

Bulk update premium currency from CSV

POST
/v1/users/bulk-update-premium-currency

What this endpoint does#

Queues a CSV job that changes premium-currency balances for members identified by Email.
It is not the user bulk-update POST. Those jobs may not appear in list bulk update jobs. JSON data is not accepted here; the gateway requires a CSV file.
WARNING
This write can move money-like balances. Use a disposable member and an approved amount. Do not copy documentation examples against a live community.
INFO
Workflow
Build CSV Email,Premium Currency with optional Premium Currency_op → POST /v1/users/bulk-update-premium-currency → inspect admin API logs until a public list exists for this job type.

Quick start#

CSV headers: Email, Premium Currency, optional Premium Currency_op (add, subtract, overwrite). Operator defaults to add when omitted.

Authentication and permission#

Send Authorization: Bearer <COMMUNITY_API_KEY>. Required permission: bulkUpdateUser. Keep the key server-side.

Complete examples#

No file (400). JSON {} returns { "status": "fail", "message": "A CSV file must be provided" }.
Non-CSV upload (400). Uploaded file must be a CSV.
Queued (200). Multipart CSV field data plus log_name returns:
{
  "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 )"
  }
}
There is no job id in this body. Treat emails as synthetic.

Success and readback#

HTTP 200 means the CSV was accepted, not that balances applied. Confirm on an approved read path for that community. The public user bulk list filters bulk-update-users jobs. Do not assume premium-currency jobs appear there.
CHECK
CSV only
If you send JSON data, expect A CSV file must be provided. Use multipart CSV.

Errors and recovery#

StatusWhenRecovery
400 A CSV file must be providedMissing file or JSON bodySend multipart CSV field data.
400 Uploaded file must be a CSVWrong file typeUpload CSV.
401Missing or invalid tokenAdd a valid community key with bulkUpdateUser.

Retry safety#

WARNING
Exact retry
Do not retry timeouts without checking whether a job already landed. Duplicate add rows change balances again. There is no idempotency key.

Gotchas#

Worker requires Email and Premium Currency.
This is not Bulk update users from CSV.
Do not use bulk user CSV to create store products.

Next steps#

Bulk user updates
Use the user bulk POST when the row is profile, XP, coins, roles, or custom fields rather than premium currency.

Request

Body Params multipart/form-data

Responses

🟢200OK
application/json
Request completed successfully.
Bodyapplication/json

🟠400Bad Request
🟠401Unauthorized
🟠403Forbidden
🟠409
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://adss-integration.returning.ai/apis/v1/users/bulk-update-premium-currency' \
--form 'data=@"example.csv"' \
--form 'log_name=""'
Response Response Example
200 - Success Example
{
    "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 )"
    }
}
Modified at 2026-08-19 18:36:38
Previous
Bulk update users from CSV
Next
Channels
Built with