> ## Documentation Index > Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt > Use this file to discover all available pages before exploring further. # List payout transactions > List past payout runs with their per-vendor batches, for the whole shop or a single vendor. Requires the `admin:payouts` permission. ## OpenAPI ````yaml openapi-merchant.json GET /payouts/transactions openapi: 3.0.0 info: title: PuppetVendors Merchant API V2 version: 2.0.0 description: >- The endpoints reachable with a merchant API key (`mk_live_…`), minted from Settings → API Access in the PuppetVendors admin. A merchant key administers users and vendors, and renews its own token. Everything else in the V2 API, including orders, products, payouts, fulfillments and documents, stays on the v1 API token and is refused here with a 403. Keys are revealed once at creation; rotating one leaves the previous key working for a 24 hour grace window. contact: name: PuppetVendors Support url: https://puppetvendors.com license: name: Proprietary servers: - url: https://production-api.puppetvendors.com description: Production - url: http://localhost:8082 description: Local development security: - bearerAuth: [] tags: - name: Auth description: Authentication endpoints for obtaining and refreshing API tokens - name: Portal - Auth description: Vendor portal authentication endpoints (vendor user login, token refresh) - name: Products description: Product management and synchronization - name: Orders description: Order retrieval and management - name: Payouts description: Vendor payout information - name: Fulfillments description: Order fulfillment operations - name: Reports description: Vendor sales reports and analytics - name: Vendors description: Vendor management operations - name: Settings description: Settings endpoints for vendor configuration and management - name: Users description: User account management - name: Shop description: Shop configuration and settings - name: Commissions description: Commission rate management - name: Integrations description: Vendor integration configuration endpoints - name: Line Items description: Order line item operations paths: /payouts/transactions: get: tags: - Payouts summary: List payout transactions description: >- List past payout runs with their per-vendor batches, for the whole shop or a single vendor. Requires the `admin:payouts` permission. operationId: listMerchantPayoutTransactions parameters: - in: query name: vendorId schema: type: string description: >- Only runs that paid this vendor, with batches narrowed to its batches example: 507f1f77bcf86cd799439012 - in: query name: status schema: type: string enum: - pending - paid - failed - cancelled description: Only batches in this mapped status (and the runs that have one) - in: query name: dateMin schema: type: string description: Created-at lower bound, YYYY-MM-DD (shop timezone) or ISO - in: query name: dateMax schema: type: string description: Created-at upper bound, YYYY-MM-DD (shop timezone) or ISO - in: query name: search schema: type: string maxLength: 200 description: Substring search on transactionId or batchId - in: query name: first schema: type: integer minimum: 1 maximum: 100 description: Number of runs to return (most recent first) - in: query name: after schema: type: string description: Cursor for forward pagination - in: query name: last schema: type: integer minimum: 1 maximum: 100 description: Number of runs to return (backward pagination) - in: query name: before schema: type: string description: Cursor for backward pagination responses: '200': description: Payout runs in the standard cursor envelope content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: edges: type: array items: type: object properties: node: type: object required: - _id - transactionId - processedAt - payoutMethod - amount - itemCount - batches properties: _id: type: string description: The run's id transactionId: type: string nullable: true example: 8Q4COZI1FA processedAt: type: string format: date-time payoutMethod: type: string nullable: true example: paypalConnected description: > The method the run was recorded with, returned exactly as stored. This is NOT the vocabulary of GET /payouts/pending. - Paid through a gateway: `stripeConnected`, `paypalConnected` (PayPal Payouts), `globalPayoutConnected`. - Logged by the merchant as paid outside the app: `bankTransfer`, `paypal`, `cash`, `other`. Here `paypal` means a PayPal payment made outside the platform, not a PayPal Payouts run. - `null` on some older runs. Runs started with POST /payouts/make-payment only write `stripeConnected`, `paypalConnected`, `globalPayoutConnected` or `other` (method `manual`). A retry or mark-paid keeps the run's original value. amount: type: number description: Total of the listed batches' amounts itemCount: type: number description: Total of the listed batches' itemCount batches: type: array items: type: object properties: batchId: type: string vendorId: type: string nullable: true vendorName: type: string nullable: true amount: type: number nullable: true itemCount: type: number description: >- Order line items + custom items in the batch status: type: string enum: - pending - paid - failed - cancelled reason: type: object nullable: true description: >- The classified failure reason (code + params); null when unrecognised gatewayRef: type: object nullable: true properties: gateway: type: string enum: - stripe - paypal refId: type: string markAsPaid: type: object nullable: true properties: marked: type: boolean enum: - true method: type: string nullable: true comments: type: string nullable: true cursor: type: string pageInfo: $ref: '#/components/schemas/PageInfo' '400': description: Invalid filters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Forbidden - merchant scope with admin:payouts required, or MERCHANT_PAYOUTS_API_NOT_ENABLED (the payouts API is not enabled for this store) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: PageInfo: type: object required: - hasNextPage - hasPreviousPage properties: hasNextPage: type: boolean description: Whether there are more items after the current page hasPreviousPage: type: boolean description: Whether there are more items before the current page startCursor: type: string description: Cursor for the first item in the page nullable: true endCursor: type: string description: Cursor for the last item in the page nullable: true totalCount: type: integer description: Total number of items (may not always be available) nullable: true ErrorResponse: type: object required: - success - error properties: success: type: boolean enum: - false description: Indicates the request failed error: type: object required: - message properties: message: type: string description: Human-readable error message example: Resource not found code: type: string description: >- Stable machine-readable error code. The frontend uses this as its localisation key (e.g. errors.api.). Server errors always report INTERNAL_SERVER_ERROR. example: NOT_FOUND errorId: type: string description: >- Correlation id for support/log lookup. Present on opaque 5xx responses so a user can quote a reference for the underlying (server-side logged) error. example: err_1783365360839_j281w7b details: type: object description: >- Additional client-error context (e.g. field-level validation errors). Never populated for server errors. securitySchemes: bearerAuth: type: apiKey in: header name: x-access-token description: >- JWT minted from a merchant API key (`mk_live_…`) by POST /authenticate. Send the token value directly, with no "Bearer" prefix. Tokens last 14 days and can be renewed at POST /refresh-token; revoking the key refuses the next request made with any token minted from it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.