1. Bulk Operations
Returning.AI
  • Getting Started
  • 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
  • Chart Analysis
    • Create Analysis
      POST
    • Get Analysis
      GET
    • Update Analysis
      PATCH
    • Delete Analysis
      DELETE
    • List Analyses
      GET
    • Append Drawings
      POST
  • Rewards & Redemptions
    • Redemption lifecycle
    • Store catalog to redemptions
    • Update redemption order status or refund
      PUT
    • List redemption orders by user email
      POST
    • List redemption statuses
      POST
    • Get redemption status by ID
      POST
    • List redemption orders by community
      POST
    • Create redemption order status
      POST
    • Get redemption order status history
      POST
    • List redemption orders by custom-field identifier
      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
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Loyalty Points
      • Create loyalty points export
      • Get loyalty points export status
      • Get loyalty points export download link
    • Quizzes
      • Create quiz
      • List quizzes
      • Get quiz
      • Update quiz
      • Delete quiz
      • Add quiz question
      • Update quiz question
      • Delete quiz question
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
    • Send Message
    • Reply Message
    • React Message
    • Upload message images
  • Users
    • User directory and provisioning
    • Get Users with Filters
    • Create New User
    • Get User Data
    • Manage User Account
    • Get User Milestones
    • Update User Data, Identifier, And Roles
  • 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 journey
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • 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
      • Create products in bulk
      • Create product with vouchers
      • Update products in bulk
      • 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
  • User Fields
    • User field definitions and history
    • User Field History
      • List Community User-Field History
      • List One Field Across Users
      • List One User Across Fields
      • List One User's One Field
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Create A User Field Definition
    • Get A User Field Definition
    • Update A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • 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
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Register user with password
      • Verify user email
      • Log in user with password
      • Secure Auth
    • 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
  • Community Logs
    • Retrieve and export community logs
  1. Bulk Operations

Bulk update premium currency from CSV

POST
https://sgtr-integration.returning.ai/apis/v1/users/bulk-update-premium-currency
Bulk Operations

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>. Legacy production permission: bulkUpdateUser. After the dedicated-permission rollout, transition mode accepts bulkUpdatePremiumCurrency OR legacy bulkUpdateUser. Community strict mode requires bulkUpdatePremiumCurrency; migrate the intended grants before enabling strict mode. 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 )"
  }
}
With hardening OFF, there is no job id in this body. With H5_INTAKE_IDEMPOTENCY enabled for the community on an updated deployment, data.jobId is additive. 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. Hardening OFF has no idempotency guarantee. When Returning.AI enables H5_INTAKE_IDEMPOTENCY on the updated deployment, optional Idempotency-Key (visible ASCII,1–255 bytes) replays the same route/community/file/options for24 hours; changed content returns409 IDEMPOTENCY_CONFLICT and an active intake returns409 IDEMPOTENCY_KEY_IN_PROGRESS. Do not rely on it after expiry. These controls default OFF; check your cohort before retrying.

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

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
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://sgtr-integration.returning.ai/apis/v1/users/bulk-update-premium-currency' \
--header 'Authorization: Bearer <token>' \
--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-10-04 04:56:58
Previous
Bulk update users from CSV
Next
Create Analysis
Built with