> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ListPayouts # Package: wixPaymentsProvider # Namespace: PayoutsService # Method link: https://dev.wix.com/docs/api-reference/business-management/payments/wix-payments-provider/payouts/list-payouts.md ## Permission Scopes: View settlement reports and payouts: SCOPE.PAYMENTS.PAYOUTS-VIEW-FOR-SITE ## Introduction Retrieves a paginated list of payouts for the specified Wix Payments account. Supports optional filters by account profile and by creation date range. A newly created payout can take a short time to appear in the results. Calls are limited to 100 requests per 10 seconds per caller. Requests over the limit fail with a `RESOURCE_EXHAUSTED` error and the message `The request was throttled`. --- ## REST API ### Schema ``` Method: listPayouts Description: Retrieves a paginated list of payouts for the specified Wix Payments account. Supports optional filters by account profile and by creation date range. A newly created payout can take a short time to appear in the results. Calls are limited to 100 requests per 10 seconds per caller. Requests over the limit fail with a `RESOURCE_EXHAUSTED` error and the message `The request was throttled`. URL: https://www.wixapis.com/wixpay-payouts/v4/payouts Method: GET # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: accountId Method parameters: query param name: accountId | type: accountId | description: GUID of the Wix Payments account whose payouts to list. Retrieve account GUIDs from the Accounts API. | required: true | validation: format GUID query param name: accountProfileId | type: accountProfileId | description: GUID of the Wix Payments account profile to filter by. When omitted, payouts across all profiles of the account are returned. Retrieve profile GUIDs from the Accounts API. | validation: format GUID query param name: createdAfter | type: createdAfter | description: Returns only payouts created on or after this date and time. The date and time itself is included. | validation: format date-time query param name: createdBefore | type: createdBefore | description: Returns only payouts created before this date and time. The date and time itself is excluded. | validation: format date-time param name: paging | type: Paging - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 param name: sort | type: Sorting - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: origin | type: AddressLocation | description: Origin point for geo-distance sorting on a GEO field results are ordered by distance from this point (ASC = nearest first, DESC = farthest first). - name: latitude | type: number | description: Address latitude. | validation: format double - name: longitude | type: number | description: Address longitude. | validation: format double Return type: ListPayoutsResponse - name: payouts | type: array | description: List of retrieved payouts. - name: id | type: string | description: Payout GUID. | validation: format GUID - name: accountId | type: string | description: GUID of the Wix Payments account that owns the payout. Retrieve account GUIDs from the Accounts API. | validation: format GUID - name: accountProfileId | type: string | description: GUID of the Wix Payments account profile that owns the payout. A Wix Payments account has 1 or more profiles. Each profile has its own balance and its own payouts. Most merchants have 1 profile. Retrieve profile GUIDs from the Accounts API. | validation: format GUID - name: createdDate | type: string | description: Date and time the payout was created. The payout is created before the underlying transfer is initiated at the bank. Once initiated, the funds typically reach the merchant's bank account within 3 to 5 business days, depending on the receiving bank. | validation: format date-time - name: amount | type: Money | description: Amount of the transfer to the merchant's bank account. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. - name: status | type: PayoutStatus | description: Lifecycle status of the payout. `SENT` means the bank rail accepted the transfer for delivery. `FAILED` means the receiving bank rejected the transfer. A `SENT` status doesn't guarantee that the funds were delivered to the merchant. The bank rail doesn't provide a delivery acknowledgement, and a payout in `SENT` can later transition to `FAILED` if the receiving bank rejects the transfer. See the per-value documentation on `PayoutStatus` for details. - enum: - UNKNOWN: Unknown payout status. Not returned by the API. - SENT: The bank rail accepted the transfer. Funds are en route to the merchant's bank account. Acceptance isn't the same as delivery. A `SENT` payout can still transition to `FAILED` if the receiving bank rejects the transfer. The bank rail's return window is up to 60 days for ACH and up to 13 months for SEPA. - FAILED: The bank rail rejected the transfer. See `failureReason` for the cause. The funds remain in the merchant's Wix Payments balance. - name: estimatedArrivalDateV2 | type: string | description: Estimated date for when the funds should arrive at the merchant's bank account, in `YYYY-MM-DD` format. The estimated arrival date is a prediction, not a guarantee. Actual arrival depends on the receiving bank's processing and may be later. | validation: format LOCAL_DATE - name: failureReason | type: PayoutFailureReason | description: Reason the bank rail rejected the transfer. Returned only when `status` is `FAILED`. - name: code | type: PayoutFailureCode | description: Why the bank rail rejected the transfer. - enum: - GENERIC_PAYOUT_FAILURE: Generic failure with no more specific reason available from the bank rail. This value is also returned when no failure reason is known. Clients can't distinguish "unknown" from "generic" using this code alone. - ACCOUNT_CLOSED: The merchant's bank account is closed. The merchant must provide new bank account details before further payouts can succeed. - ACCOUNT_FROZEN: The merchant's bank account is frozen, for example due to a hold placed by the bank. The merchant must resolve the hold with their bank before further payouts can succeed. - BANK_ACCOUNT_RESTRICTED: The merchant's bank account is restricted from receiving the transfer. For example, the account type or status doesn't permit incoming credits. - BANK_OWNERSHIP_CHANGED: Ownership of the merchant's bank account changed and the rail no longer recognises the previously-recorded owner. New bank details are required. - COULD_NOT_PROCESS: The receiving bank couldn't process the transfer for an unspecified reason. A subsequent payout attempt may succeed. - DEBIT_NOT_AUTHORIZED: The merchant's bank declined the debit authorisation associated with the transfer. The merchant must contact their bank to authorise Wix Payments payouts. - INCORRECT_ACCOUNT_HOLDER_NAME: The account holder name on file doesn't match the name the receiving bank has on record. The merchant must correct the account holder name. - INVALID_ACCOUNT_DETAILS_CITY: The city in the bank account details is invalid for the receiving bank. - INVALID_ACCOUNT_NUMBER: The bank account number is invalid. The format is wrong or the account doesn't exist. - INVALID_CURRENCY: The payout currency isn't supported by the receiving bank account. - INVALID_ROUTING_NUMBER: The routing number (US) is invalid or doesn't match the receiving bank. - INVALID_SORT_CODE: The sort code (UK) is invalid or doesn't match the receiving bank. - NO_ACCOUNT: No bank account is on file for the merchant. The merchant must add bank details before payouts can succeed. - TECHNICAL_ERROR: A technical error at the bank rail prevented the transfer. A subsequent payout attempt may succeed. - name: bankTransferReference | type: string | description: Reference returned by the bank rail once the transfer is initiated. For example, an ACH trace number or a SEPA reference. Use this value to reconcile against the merchant's bank statement. Empty until the bank rail returns a reference. | validation: maxLength 500 - name: cashAdvanceIncluded | type: boolean | description: Whether the payout `amount` includes funds from a Wix Capital cash advance taken out by the merchant. If `false`, the amount comes only from the merchant's sales proceeds. - name: metadata | type: PagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: total | type: integer | description: Total number of items that match the query. | validation: format int32 - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. ``` ### Examples ### List payouts for an account Retrieves a paginated list of payouts for the specified Wix Payments account. ```curl curl -X GET \ 'https://www.wixapis.com/wixpay-payouts/v4/payouts?accountId=e4280592-0121-44d7-ad1c-5ac57a0fb36d&paging.limit=2&paging.offset=0' \ -H 'Authorization: ' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.payments.payouts.listPayouts(accountId, options) Description: Retrieves a paginated list of payouts for the specified Wix Payments account. Supports optional filters by account profile and by creation date range. A newly created payout can take a short time to appear in the results. Calls are limited to 100 requests per 10 seconds per caller. Requests over the limit fail with a `RESOURCE_EXHAUSTED` error and the message `The request was throttled`. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: accountId Method parameters: param name: accountId | type: string | description: GUID of the Wix Payments account whose payouts to list. Retrieve account GUIDs from the Accounts API. | required: true | validation: format GUID param name: options | type: ListPayoutsOptions none - name: accountProfileId | type: string | description: GUID of the Wix Payments account profile to filter by. When omitted, payouts across all profiles of the account are returned. Retrieve profile GUIDs from the Accounts API. | validation: format GUID - name: createdBefore | type: Date | description: Returns only payouts created before this date and time. The date and time itself is excluded. - name: createdAfter | type: Date | description: Returns only payouts created on or after this date and time. The date and time itself is included. - name: sort | type: Sorting | description: Sort order for the result list. Supported `fieldName` values: `created_date` (snake_case, not auto-converted). At most 1 sort field is allowed. - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: origin | type: AddressLocation | description: Origin point for geo-distance sorting on a GEO field results are ordered by distance from this point (ASC = nearest first, DESC = farthest first). - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: paging | type: Paging | description: Offset-based paging. `limit` supports values from `1` to `20`. Default: `limit` is `20`, `offset` is `0`. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 Return type: PROMISE - name: payouts | type: array | description: List of retrieved payouts. - name: _id | type: string | description: Payout GUID. | validation: format GUID - name: accountId | type: string | description: GUID of the Wix Payments account that owns the payout. Retrieve account GUIDs from the Accounts API. | validation: format GUID - name: accountProfileId | type: string | description: GUID of the Wix Payments account profile that owns the payout. A Wix Payments account has 1 or more profiles. Each profile has its own balance and its own payouts. Most merchants have 1 profile. Retrieve profile GUIDs from the Accounts API. | validation: format GUID - name: _createdDate | type: Date | description: Date and time the payout was created. The payout is created before the underlying transfer is initiated at the bank. Once initiated, the funds typically reach the merchant's bank account within 3 to 5 business days, depending on the receiving bank. - name: amount | type: Money | description: Amount of the transfer to the merchant's bank account. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. - name: status | type: PayoutStatus | description: Lifecycle status of the payout. `SENT` means the bank rail accepted the transfer for delivery. `FAILED` means the receiving bank rejected the transfer. A `SENT` status doesn't guarantee that the funds were delivered to the merchant. The bank rail doesn't provide a delivery acknowledgement, and a payout in `SENT` can later transition to `FAILED` if the receiving bank rejects the transfer. See the per-value documentation on `PayoutStatus` for details. - enum: - UNKNOWN: Unknown payout status. Not returned by the API. - SENT: The bank rail accepted the transfer. Funds are en route to the merchant's bank account. Acceptance isn't the same as delivery. A `SENT` payout can still transition to `FAILED` if the receiving bank rejects the transfer. The bank rail's return window is up to 60 days for ACH and up to 13 months for SEPA. - FAILED: The bank rail rejected the transfer. See `failureReason` for the cause. The funds remain in the merchant's Wix Payments balance. - name: estimatedArrivalDateV2 | type: string | description: Estimated date for when the funds should arrive at the merchant's bank account, in `YYYY-MM-DD` format. The estimated arrival date is a prediction, not a guarantee. Actual arrival depends on the receiving bank's processing and may be later. | validation: format LOCAL_DATE - name: failureReason | type: PayoutFailureReason | description: Reason the bank rail rejected the transfer. Returned only when `status` is `FAILED`. - name: code | type: PayoutFailureCode | description: Why the bank rail rejected the transfer. - enum: - GENERIC_PAYOUT_FAILURE: Generic failure with no more specific reason available from the bank rail. This value is also returned when no failure reason is known. Clients can't distinguish "unknown" from "generic" using this code alone. - ACCOUNT_CLOSED: The merchant's bank account is closed. The merchant must provide new bank account details before further payouts can succeed. - ACCOUNT_FROZEN: The merchant's bank account is frozen, for example due to a hold placed by the bank. The merchant must resolve the hold with their bank before further payouts can succeed. - BANK_ACCOUNT_RESTRICTED: The merchant's bank account is restricted from receiving the transfer. For example, the account type or status doesn't permit incoming credits. - BANK_OWNERSHIP_CHANGED: Ownership of the merchant's bank account changed and the rail no longer recognises the previously-recorded owner. New bank details are required. - COULD_NOT_PROCESS: The receiving bank couldn't process the transfer for an unspecified reason. A subsequent payout attempt may succeed. - DEBIT_NOT_AUTHORIZED: The merchant's bank declined the debit authorisation associated with the transfer. The merchant must contact their bank to authorise Wix Payments payouts. - INCORRECT_ACCOUNT_HOLDER_NAME: The account holder name on file doesn't match the name the receiving bank has on record. The merchant must correct the account holder name. - INVALID_ACCOUNT_DETAILS_CITY: The city in the bank account details is invalid for the receiving bank. - INVALID_ACCOUNT_NUMBER: The bank account number is invalid. The format is wrong or the account doesn't exist. - INVALID_CURRENCY: The payout currency isn't supported by the receiving bank account. - INVALID_ROUTING_NUMBER: The routing number (US) is invalid or doesn't match the receiving bank. - INVALID_SORT_CODE: The sort code (UK) is invalid or doesn't match the receiving bank. - NO_ACCOUNT: No bank account is on file for the merchant. The merchant must add bank details before payouts can succeed. - TECHNICAL_ERROR: A technical error at the bank rail prevented the transfer. A subsequent payout attempt may succeed. - name: bankTransferReference | type: string | description: Reference returned by the bank rail once the transfer is initiated. For example, an ACH trace number or a SEPA reference. Use this value to reconcile against the merchant's bank statement. Empty until the bank rail returns a reference. | validation: maxLength 500 - name: cashAdvanceIncluded | type: boolean | description: Whether the payout `amount` includes funds from a Wix Capital cash advance taken out by the merchant. If `false`, the amount comes only from the merchant's sales proceeds. - name: metadata | type: PagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: total | type: integer | description: Total number of items that match the query. | validation: format int32 - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. ``` ### Examples ### List payouts for an account Retrieves a paginated list of payouts for the specified Wix Payments account, sorted by creation date. ```javascript import { payouts } from "@wix/payments"; const accountId = "e4280592-0121-44d7-ad1c-5ac57a0fb36d"; const options = { createdAfter: "2020-01-01T00:00:00Z", createdBefore: "2020-12-31T23:59:59Z", sort: { fieldName: "created_date", order: "DESC", }, paging: { limit: 2, offset: 0, }, }; async function listPayouts() { const response = await payouts.listPayouts(accountId, options); } /* Promise resolves to: * { * "payouts": [ * { * "_id": "f381e42d-ae6f-4abb-b7c7-e8f7e3eea0db", * "accountId": "e4280592-0121-44d7-ad1c-5ac57a0fb36d", * "accountProfileId": "444d5860-2e05-42bd-8743-b544c237657f", * "_createdDate": "2020-10-07T11:32:34.314Z", * "amount": { * "value": "4024.16", * "currency": "USD" * }, * "status": "SENT", * "estimatedArrivalDateV2": "2020-10-08", * "cashAdvanceIncluded": false * }, * { * "_id": "6dc90461-b2aa-4fc6-a06a-40532d8de62c", * "accountId": "e4280592-0121-44d7-ad1c-5ac57a0fb36d", * "accountProfileId": "444d5860-2e05-42bd-8743-b544c237657f", * "_createdDate": "2020-08-05T11:27:25.902Z", * "amount": { * "value": "6103.79", * "currency": "USD" * }, * "status": "SENT", * "estimatedArrivalDateV2": "2020-08-10", * "cashAdvanceIncluded": false * } * ], * "metadata": { * "count": 2, * "offset": 0, * "total": 11 * } * } */ ``` ### listPayouts (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { payouts } from '@wix/payments'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { payouts }, // Include the auth strategy and host as relevant }); async function listPayouts(accountId,options) { const response = await myWixClient.payouts.listPayouts(accountId,options); }; ``` ---