Learn about partner fees, residuals, and reconciliation. During the onboarding process, you'll enter into a partner agreement with Moov. Your buy rate is configured as a fee plan and assigned to your partner account. You can view your active partner pricing agreement using the `GET` partner pricing [endpoint](https://docs.moov.io/api/moov-accounts/partner-billing/list-partner-agreements/). ## Fees and revenue You can retrieve information about fees, including partner costs and merchant-generated revenue, using the `GET` fees [endpoint](https://docs.moov.io/api/moov-accounts/billing/get-fees/). Use this endpoint for partner fees by passing in your partner `accountID` and for merchant fees passing in the merchant's `accountID`. List all partner fees. Partner fees include all the fees charged to you, per your buy-rate. Use your partner `accountID` in the route. To find your partner account ID, navigate to **Settings** in the side navigation. Your partner account ID is located below your account name and logo. ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/fees" \ -H "Authorization: Bearer {token}" \ ``` Response: ```json [\ {\ "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ "walletID": "0eb7d670-c252-422a-892d-002136c358e0",\ "createdOn": "2019-08-24T14:15:22Z",\ "feeName": "string",\ "amount": {\ "currency": "USD",\ "valueDecimal": "12.987654321"\ },\ "generatedBy": {\ "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",\ "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",\ "disputeID": "5720fd8c-f7a6-4c10-a19a-d345b5f89bec",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ "bankAccountID": "5b03c365-bcf1-4c70-aeec-29a06f15faf2"\ },\ "feeGroup": "string",\ "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"\ }\ ] ``` List all fees for a specific merchant account. Use a merchant's `accountID` in the route. To find a merchant's account ID, navigate to **Accounts** in the Dashboard and select or search for a merchant's account. Their merchant account ID is located below their name and logo. You can also find a merchant account ID using the [accounts API](https://docs.moov.io/api/moov-accounts/accounts/list/). ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/fees" \ -H "Authorization: Bearer {token}" \ ``` Response: ```json [\ {\ "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ "walletID": "0eb7d670-c252-422a-892d-002136c358e0",\ "createdOn": "2019-08-24T14:15:22Z",\ "feeName": "Card decline fee",\ "amount": {\ "currency": "USD",\ "valueDecimal": "15.987444321"\ },\ "generatedBy": {\ "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",\ "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",\ "disputeID": "5720fd8c-f7a6-4c10-a19a-d345b5f89bec",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ "bankAccountID": "5b03c365-bcf1-4c70-aeec-29a06f15faf2"\ },\ "feeGroup": "string",\ "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"\ }\ ] ``` ## Reconcile costs and revenue Reconcile your costs and revenue _without revenue share._ Partner processing costs are debited from your wallet in real time as the billable events occur and fees are created. Merchant fees collected are credited to your wallet in real time. To reconcile costs for a specific period, use the `GET` fees [endpoint](https://docs.moov.io/api/moov-accounts/billing/get-fees/) and query by the date range. The `amount` and `feeGroup` are included in the response. You can use these fields to filter fees. ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/fees?startDateTime=2025-12-24T14:15:22Z?endDateTime=2026-02-24T14:15:22Z" \ -H "Authorization: Bearer {token}" \ ``` Response: ```json 1[\ 2 {\ 3 "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",\ 4 "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ 5 "walletID": "0eb7d670-c252-422a-892d-002136c358e0",\ 6 "createdOn": "2026-01-24T14:15:22Z",\ 7 "feeName": "string",\ 8 "amount": {\ 9 "currency": "USD",\ 10 "valueDecimal": "12.987654321"\ 11 },\ 12 "generatedBy": {\ 13 "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",\ 14 "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",\ 15 "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ 16 },\ 17 "feeGroup": "string",\ 18 "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"\ 19 }\ 20] ``` ## Reconcile revenue share residuals While partner fees and merchant fee revenue are recorded throughout the period for reporting purposes, Moov generates a single residual settlement transaction one business day after the billing period closes with one of the following outcomes: - Positive residual: wallet is credited - Negative residual: wallet is debited The wallet transaction's `sourceID` corresponds to the `residualID`, which you can use to reconcile the settlement. ### Calculations A residual represents your share of net income: `netIncome` = `merchantFees` − `partnerCost` Fee revenue is the `merchantFees` on the residual. Fee revenue can also be retrieved using the `GET` fee revenue [endpoint](https://docs.moov.io/api/moov-accounts/partner-billing/list-fee-revenue/). Your `residualAmount` = `netIncome` x `revenueShare` ### Calculate ### Retrieve the residual summary Use the `residualID` to retrieve the residual record with the `GET` residuals [endpoint](https://docs.moov.io/api/moov-accounts/partner-billing/get-residuals/). ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/residuals/{residualID}" \ -H "Authorization: Bearer {token}" \ ``` The response provides the totals used in the calculation: ```json { "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69", "partnerAccountID": "c197cd40-7745-4413-8f3b-ec962d1b5225", "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" }, "moovShare": { "currency": "USD", "valueDecimal": "12.987654321" }, "createdOn": "2019-08-24T14:15:22Z" } ``` ### Reconcile fee revenue To view the merchant fee revenue entries included in the residual calculation, use your partner `accountID` with the `GET` fee revenues [endpoint](https://docs.moov.io/api/moov-accounts/partner-billing/list-fee-revenue/) and query the `residualID`. ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/fee-revenue?residualID={residualID}" \ -H "Authorization: Bearer {token}" \ ``` This returns all fee revenue items applied to the residual. Optionally, you can group results by `feeGroup` to review the revenue breakdown. The total should match `merchantFees` from the previous step. ```json [\ {\ "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",\ "walletID": "0eb7d670-c252-422a-892d-002136c358e0",\ "createdOn": "2019-08-24T14:15:22Z",\ "feeName": "string",\ "amount": {\ "currency": "USD",\ "valueDecimal": "12.987654321"\ },\ "generatedBy": {\ "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",\ "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",\ "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9"\ },\ "feeGroup": "string",\ "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"\ }\ ] ``` ### Reconcile partner costs To view the partner fees included in the residual calculation, use your partner accountID with the `GET` fees [endpoint](https://docs.moov.io/api/moov-accounts/billing/get-fees/) and query the `residualID`. ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/fees?residualID={residualID}" \ -H "Authorization: Bearer {token}" \ ``` This returns all partner cost entries applied to the residual. You may optionally group results by `feeGroup` to review the cost breakdown. The total should match `partnerCosts` from the previous step. ### Confirm result match Look at the `residualAmount` from the previous step and confirm the calculations and the `residualAmount` match. ## Partner statements Moov generates monthly statements for each partner account. Statements are made available on the first day of the following month for the previous month's activity. Partner statements will include a summary of the following: - Merchant fees collected for each fee category - Partner fees assessed for each fee category - Net income for each fee category - Residual payment (for revenue-share partners) - Monthly partner platform fees (if applicable) - Interchange report Use the `GET` list statements [endpoint](https://docs.moov.io/api/moov-accounts/billing/list-statements/) to list all statements. You can filter by `billingPeriodStartDate` and `billingPeriodEndDate` to specify the time period. To download a specific statement in your preferred format (PDF or JSON), use the `GET` statements [endpoint](https://docs.moov.io/api/moov-accounts/billing/get-statement/) with an `accept` header. Statements are available in the [Dashboard](https://docs.moov.io/guides/dashboard/settings/documents/#merchant-statements) and [API](https://docs.moov.io/api/moov-accounts/billing/). You can subscribe to the `statement.created` [webhook](https://docs.moov.io/guides/webhooks/webhook-events/#billing) to receive real-time notifications on availability. ### Access statements Use the list statements [endpoint](https://docs.moov.io/api/moov-accounts/billing/list-statements/) to list all statements. You can filter by `billingPeriodStartDate` and `billingPeriodEndDate` to specify the time period. ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/statements?billingPeriodStartDate=2025-06-10T23:00:00Z" \ -H "Authorization: Bearer {token}" ``` ```zsh curl -X GET "https://api.moov.io/accounts/{accountID}/statements/{statementID}" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/pdf" ``` In the Dashboard, statements can be accessed by navigating **Settings > Documents** and clicking on the **Statements** tab. Statement availability via email is coming soon.