Rewards sweep

Rewards sweep moves an account’s available rewards into a spend account on another Fluz account, once a day, with no action from the user. Your app connects the user’s account to an approved target account. Fluz runs the sweep. Use it when your platform collects the rewards your users earn on Fluz. For example, sweep the cashback your members earn into your platform’s operating spend account. This page covers the TGS GraphQL surface:

How it works

Fluz approves your target account, sets the spend account the rewards land in, and allowlists your app.
The user authorizes your app. Your app calls createRewardsSweepConnection with the user’s access token and your target account ID.
Once each New York calendar day, Fluz moves the user’s full available rewards balance into your target spend account.
To stop, your app calls deleteRewardsSweepConnection with the user’s access token.

In this page, the source account is the user’s account whose rewards are swept. The target account is the account that receives the money. The spend account is the target’s spend account the money lands in.

Only available rewards are swept.The sweep takes the spendable rewards balance at the moment it runs. Pending or locked rewards stay on the source account until a later sweep picks them up. Nothing is held in advance: the user can spend their rewards normally until the sweep runs.

Before you start

Contact your Fluz account manager to:

allowlist your app for rewards sweep
register your target account and the spend account the rewards should land in

Each target account has one destination spend account, and that spend account must belong to the target account.

Requirement	Value
Auth	Bearer token for the source account. Basic Auth is not supported.
Scope	`MAKE_PAYOUT_TRANSFER_SEND` (the same scope as `createTransfer`)
App	Must be allowlisted for rewards sweep by Fluz

Connect an account

Call createRewardsSweepConnection with the user’s access token. The source account always comes from the token. Pass your target account ID, not a spend account ID.

mutation {
  createRewardsSweepConnection(input: {
    targetAccountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  }) {
    rewardsSweepSourceAccountId
    sourceAccountId
    targetAccountId
  }
}

Authorization: Bearer <user-access-token>

{
  "data": {
    "createRewardsSweepConnection": {
      "rewardsSweepSourceAccountId": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "targetAccountId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }
}

Rules

A source account can be connected to one target at a time.
Calling create again with the same target is safe. It returns the existing connection.
Calling create with a different target fails while a connection exists. To change targets, disconnect first, then connect to the new target.
The source and target must be different accounts.
Fluz can also create a connection for an account from its dashboard. That connection behaves the same way and can be removed with deleteRewardsSweepConnection.

Disconnect an account

Call deleteRewardsSweepConnection with the user’s access token. It takes no input. It removes the connection for the account on the token.

mutation {
  deleteRewardsSweepConnection {
    sourceAccountId
    disconnected
  }
}

{
  "data": {
    "deleteRewardsSweepConnection": {
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "disconnected": true
    }
  }
}

disconnected is false when the account had no connection. That is not an error, so the call is safe to repeat. If you disconnect after the day’s sweep is scheduled but before the money moves, that day’s sweep is cancelled and nothing is debited.

Sweep behavior


Frequency	At most one sweep per source account per calendar day, in `America/New_York` time. Fluz sets the run time.
Amount	The full available rewards balance at the moment the sweep runs.
Zero balance	No transfer is made. The day counts as swept.
Destination	The spend account configured for the target when the day’s sweep is scheduled.
Retries	Each daily sweep has a fixed idempotency key, so a retry never moves the money twice.
Insufficient balance	If the balance changes before the money moves, the sweep re-reads the balance and retries.

What the accounts see

Each sweep is one account-to-account transfer. It appears in both accounts’ activity with the description Rewards transfer.

Account	Activity row
Source	Money sent from the Fluz rewards balance to the target account and spend account
Target	Money received from the source account into the spend account

Checking a connection

There is no query to read a connection or past sweeps today. Store the connection on your side from the createRewardsSweepConnection and deleteRewardsSweepConnection responses. Confirm sweeps from the target account’s transaction activity.

Errors

Failures use the standard GraphQL error envelope.

{
  "data": null,
  "errors": [
    {
      "message": "Target account is not approved for rewards sweep",
      "extensions": {
        "code": "APPLICATIONS-0012",
        "errorName": "InvalidArgument",
        "statusCode": 422
      }
    }
  ]
}

Errors are checked in this order:

Code	Message	When
`AUTH-0002`	Basic auth is not supported for this operation.	The request used Basic Auth. Use the user’s Bearer token.
`AUTH-0031`	Insufficient permissions: `<mutation>` requires MAKE_PAYOUT_TRANSFER_SEND	The token is missing the `MAKE_PAYOUT_TRANSFER_SEND` scope.
`AUTH-0008`	Authenticated account is required.	The token does not resolve to an account.
`AUTH-0008`	App is not allowed to create a rewards sweep connection	Your app is not allowlisted for rewards sweep. Delete returns the same message with “delete”.
`APPLICATIONS-0012`	Target account is not approved for rewards sweep	`targetAccountId` is not a registered target, or has no spend account. Create only.
`APPLICATIONS-0012`	Source and target accounts must be different.	The token’s account is the target account. Create only.
`APPLICATIONS-0012`	Source account is already connected to a rewards sweep target	The account is connected to a different target. Disconnect first. Create only.

A missing, invalid or expired access token is rejected before GraphQL runs and returns an HTTP error, not a GraphQL error. See Authentication.

​How it works

​Before you start

​Connect an account

​Disconnect an account

​Sweep behavior

​What the accounts see

​Checking a connection

​Errors

How it works

Before you start

Connect an account

Disconnect an account

Sweep behavior

What the accounts see

Checking a connection

Errors