> ## 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. # Retry a payout batch > Retry a payout batch that was rejected. Runs asynchronously; poll the transaction for the result. Requires the `admin:payouts:make_payment` permission. ## OpenAPI ````yaml openapi-merchant.json POST /payouts/batches/{batchId}/retry 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/batches/{batchId}/retry: post: tags: - Payouts summary: Retry a payout batch description: >- Retry a payout batch that was rejected. Runs asynchronously; poll the transaction for the result. Requires the `admin:payouts:make_payment` permission. operationId: retryPayoutBatch parameters: - in: path name: batchId required: true schema: type: string minLength: 1 maxLength: 64 description: The legacy batch id (a random 10-char string, not an ObjectId) example: a1b2c3d4e5 - in: header name: Idempotency-Key required: true schema: type: string minLength: 8 maxLength: 128 description: >- Caller-chosen dedupe key, unique per payout you intend to make. Retrying the same request with the same key returns the same requestId and never starts a second run; the engine deduplicates on it. The key is bound to its request (the batchId and the body): the same key on another batch or with a different body is refused with 422 IDEMPOTENCY_KEY_REUSED. A NEW key is a NEW payout: always retry a timed-out or failed-to-connect request with its original key, never a fresh one, or the same items can be paid twice. responses: '200': description: >- Replay of a run that already completed under this Idempotency-Key; nothing new was started and the stored result is returned content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: requestId: type: string status: type: string enum: - completed replay: type: boolean enum: - true transactionId: type: string nullable: true totalPayout: type: number nullable: true '202': description: Retry accepted; executing asynchronously content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: requestId: type: string transactionId: type: string nullable: true description: >- The transaction the batch belongs to; the poll key for GET /payouts/make-payment/{transactionId} status: type: string example: processing dryRun: type: boolean enum: - false '400': description: Missing/short Idempotency-Key, or a malformed batchId 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:make_payment required (admin:payouts alone is NOT enough), or MERCHANT_PAYOUTS_API_NOT_ENABLED (the payouts API is not enabled for this store) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- BATCH_NOT_FOUND, no batch with this batchId in this shop (another shop's batch reads the same as an unknown one) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- A run with this Idempotency-Key is already in flight (IDEMPOTENCY_IN_PROGRESS; details.transactionId is the poll key), or another payout run is working on this batch right now (PAYOUT_ITEMS_LOCKED; nothing was started and the key is not used up) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The Idempotency-Key was already used for a different request (IDEMPOTENCY_KEY_REUSED, details.requestId is the run it was used for; nothing is started), or the batch is not failed (BATCH_NOT_RETRYABLE, only failed batches can be retried, and not one whose payment may already have been sent (the message then says to check it with the payment provider); nothing is started and the key is not used up), or the engine rejected the retry (code and details pass through verbatim) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: 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.