List residuals
List all residuals associated with an account.
To access this endpoint using an access token
you'll need to specify the /accounts/{accountID}/profile.read scope.
GET
/accounts/{accountID}/residuals
curl -X GET "https://api.moov.io/accounts/{accountID}/residuals" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.01.00"mc, _ := moov.NewClient()
var accountID string
mc.ListResiduals(ctx, accountID)
import { Moov } from "@moovio/sdk";
const moov = new Moov({
security: {
username: "",
password: "",
},
});
async function run() {
const result = await moov.feePlans.listResiduals({
skip: 60,
count: 20,
accountID: "8b40b967-ae12-4851-8be2-7b0c39978ce7",
});
console.log(result);
}
run();declare(strict_types=1);
require 'vendor/autoload.php';
use Moov\MoovPhp;
use Moov\MoovPhp\Models\Components;
use Moov\MoovPhp\Models\Operations;
$sdk = MoovPhp\Moov::builder()
->setSecurity(
new Components\Security(
username: '',
password: '',
)
)
->build();
$request = new Operations\ListResidualsRequest(
skip: 60,
count: 20,
accountID: '8b40b967-ae12-4851-8be2-7b0c39978ce7',
);
$response = $sdk->feePlans->listResiduals(
request: $request
);
if ($response->residuals !== null) {
// handle response
}package hello.world;
import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.ListResidualsRequest;
import io.moov.sdk.models.operations.ListResidualsResponse;
import java.lang.Exception;
public class Application {
public static void main(String[] args) throws Exception {
Moov sdk = Moov.builder()
.security(Security.builder()
.username("")
.password("")
.build())
.build();
ListResidualsRequest req = ListResidualsRequest.builder()
.accountID("8b40b967-ae12-4851-8be2-7b0c39978ce7")
.skip(60L)
.count(20L)
.build();
ListResidualsResponse res = sdk.feePlans().listResiduals()
.request(req)
.call();
if (res.residuals().isPresent()) {
System.out.println(res.residuals().get());
}
}
}from moovio_sdk import Moov
from moovio_sdk.models import components
with Moov(
security=components.Security(
username="",
password="",
),
) as moov:
res = moov.fee_plans.list_residuals(account_id="8b40b967-ae12-4851-8be2-7b0c39978ce7", skip=60, count=20)
# Handle response
print(res)require 'moov_ruby'
Models = ::Moov::Models
s = ::Moov::Client.new(
security: Models::Components::Security.new(
username: '',
password: ''
)
)
req = Models::Operations::ListResidualsRequest.new(
skip: 60,
count: 20,
account_id: '8b40b967-ae12-4851-8be2-7b0c39978ce7'
)
res = s.fee_plans.list_residuals(request: req)
unless res.residuals.nil?
# handle response
endusing Moov.Sdk;
using Moov.Sdk.Models.Components;
using Moov.Sdk.Models.Requests;
var sdk = new MoovClient(security: new Security() {
Username = "",
Password = "",
});
ListResidualsRequest req = new ListResidualsRequest() {
Skip = 60,
Count = 20,
AccountID = "8b40b967-ae12-4851-8be2-7b0c39978ce7",
};
var res = await sdk.FeePlans.ListResidualsAsync(req);
// handle responseThe request completed successfully.
[
{
"residualID": "string",
"partnerAccountID": "string",
"periodStart": "2019-08-24T14:15:22Z",
"periodEnd": "2019-08-24T14:15:22Z",
"merchantFees": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"partnerCost": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"netIncome": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"revenueShare": "2.25",
"residualAmount": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}
]Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request contained missing or expired authentication.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The user is not authorized to make the request.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Request was refused due to rate limiting.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed due to an unexpected error.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed because a downstream service failed to respond.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Headers
X-Moov-Version
string
Set this header to v2026.01.00 to use the API described in this specification. When omitted, the server defaults to v2024.01.00, which may not match the behavior documented here.
Possible values:
v2026.01.00
Path parameters
accountID
string
required
Query parameters
skip
integer
<int64>
count
integer
<int64>
Default:
200startDateTime
string
<RFC-3339>
Optional date-time to inclusively filter all residuals with a period start after this date-time.
endDateTime
string
<RFC-3339>
Optional date-time to exclusively filter all residuals with a period end before this date-time.
Response
createdOn
string<date-time>
Timestamp when the residual was created.
merchantFees
object
Total amount of merchant fees collected during the period. This represents the partner's revenue from merchant fees.
Show child attributes
currency
string
required
Pattern
A 3-letter ISO 4217 currency code.
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
netIncome
object
Net income calculated as merchant fee revenue minus partner costs.
Show child attributes
currency
string
required
Pattern
A 3-letter ISO 4217 currency code.
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
partnerAccountID
string
The partner account ID this residual belongs to.
A unique identifier for a Moov resource. Supports UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) or typed format with base32-encoded UUID and type suffix (e.g., kuoaydiojf7uszaokc2ggnaaaa_xfer).
partnerCost
object
Partner's total cost (buy rate) during the period.
Show child attributes
currency
string
required
Pattern
A 3-letter ISO 4217 currency code.
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
periodEnd
string<date-time>
End date and time of the residual calculation period.
periodStart
string<date-time>
Start date and time of the residual calculation period.
residualAmount
object
The amount the partner receives as their share of the net income (netIncome × revenueShare).
Show child attributes
currency
string
required
Pattern
A 3-letter ISO 4217 currency code.
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
residualID
string
Unique identifier for this residual payment calculation.
A unique identifier for a Moov resource. Supports UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) or typed format with base32-encoded UUID and type suffix (e.g., kuoaydiojf7uszaokc2ggnaaaa_xfer).
revenueShare
string
The revenue share percentage the partner receives, expressed as a decimal string (e.g., "25.00" for 25%).
updatedOn
string<date-time>
Timestamp when the residual was last updated.