> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create batch payout > Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.
You can make payouts to one or more recipients.
Notes:
## OpenAPI ````yaml /api-reference/payments_payouts_batch_v1.json post /v1/payments/payouts openapi: 3.0.3 info: title: Payouts description: >- Use the Payouts API to make payments to multiple PayPal or Venmo recipients. The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. You can send up to 15,000 payments per call. If you integrated the Payouts API before September 1, 2017, you receive transaction reports through Payouts Reporting. The Payouts API uses the ISO 8601 Internet date and time format. version: '1.9' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment security: [] tags: - name: payouts description: >- Use the `/payouts` resource to create a batch payout, update the status for a batch payout, show the status of a batch payout with the transaction status and other data for individual payout items, and request approval for a batch payout. - name: payouts-item description: >- Use the `/payouts-item` resource to show payout item details and cancel an unclaimed payout item. - name: payouts-statistics description: >- Use the `/payouts-statistics` resource to show statistics for a batch payout by date range. - name: payouts-disbursement-notifications description: >- Use the `payouts/disbursement-notifications` resource for status updates from VENMO - name: payout-application-status description: >- Use the `/payout-applications` resource to fetch and update payout status of the application. externalDocs: url: https://developer.paypal.com/docs/api/payments.payouts-batch/v1/ paths: /v1/payments/payouts: post: tags: - payouts summary: Create batch payout description: >- Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.
You can make payouts to one or more recipients.
Notes:
operationId: payouts.post parameters: - $ref: '#/components/parameters/paypal_request_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/create_payout_request' examples: create_payout_request: value: sender_batch_header: sender_batch_id: Payouts_2018_100007 email_subject: You have a payout! email_message: You have received a payout! Thanks for using our service! items: - recipient_type: EMAIL amount: value: '9.87' currency: USD note: Thanks for your patronage! sender_item_id: '201403140001' receiver: receiver@example.com alternate_notification_method: phone: country_code: '91' national_number: '9999988888' notification_language: fr-FR - recipient_type: PHONE amount: value: '112.34' currency: USD note: Thanks for your support! sender_item_id: '201403140002' receiver: 91-734-234-1234 - recipient_type: PAYPAL_ID amount: value: '5.32' currency: USD note: Thanks for your patronage! sender_item_id: '201403140003' receiver: G83JXTJ5EHCQ2 responses: '201': description: >- A successful request returns the HTTP 201 Created status code and a JSON response body that shows the ID for the payout and payout details. To show payout status, use the payout_batch_id value that appears in the response. If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the batch_status is PENDING. The initial scan checks for syntax errors and missing or duplicated keywords. The API does not immediately validate some payout item values, such as the receiver phone numbers. content: application/json: schema: $ref: '#/components/schemas/payout' '400': description: >- Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/error' '500': description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/error' default: description: The error response. content: application/json: schema: $ref: '#/components/schemas/error' security: - Oauth2: - https://uri.paypal.com/payments/payouts components: parameters: paypal_request_id: name: PayPal-Request-Id in: header description: The server stores keys for 30 days. required: false schema: type: string minLength: 1 maxLength: 1000 pattern: ^.*$ schemas: create_payout_request: type: object title: Create Payout Request description: The create payout request. properties: sender_batch_header: $ref: '#/components/schemas/sender_batch_header' description: The sender-provided payout header for a payout request. items: $ref: '#/components/schemas/payout_item_request_list' required: - sender_batch_header - items payout: type: object title: Create Payout Response description: The create payout response. properties: batch_header: $ref: '#/components/schemas/payout_header' description: The payout header. links: $ref: '#/components/schemas/definitions-link_description_list' error: type: object title: Error description: The error details. properties: name: type: string description: The human-readable, unique name of the error. message: type: string description: The message that describes the error. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. information_link: type: string description: >- The information link, or URI, that shows detailed information about this error for the developer. readOnly: true details: $ref: '#/components/schemas/error_details_list' links: $ref: '#/components/schemas/link_description_list' required: - name - message - debug_id sender_batch_header: type: object title: Sender Batch Header description: The sender-provided payout header for a payout request. properties: sender_batch_id: type: string description: >- A sender-specified ID number. Tracks the payout in an accounting system.
Note:

PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.

If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

minLength: 0 maxLength: 256 pattern: ^.*$ recipient_type: type: string description: >- The ID type that identifies the recipient of the payment. For example, EMAIL. minLength: 0 maxLength: 13 pattern: ^.*$ email_subject: type: string description: >- The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters. minLength: 0 maxLength: 255 pattern: ^.*$ email_message: type: string description: >- The email message that PayPal sends when the payout item completes. The message is the same for all recipients. minLength: 0 maxLength: 1000 pattern: ^.*$ note: type: string description: >- The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters. minLength: 0 maxLength: 1000 pattern: ^.*$ payout_item_request_list: type: array description: An array of individual payout items. maxItems: 15000 minItems: 1 items: $ref: '#/components/schemas/payout_item_request' payout_header: type: object title: Payout Header description: >- The payout header that is returned in response to a payout header request. Shows details for an entire payout request. properties: payout_batch_id: type: string description: The PayPal-generated ID for a payout. minLength: 0 maxLength: 30 pattern: ^.*$ batch_status: $ref: '#/components/schemas/batch_enum' description: >- The PayPal-generated payout status. If the payout passes preliminary checks, the status is `PENDING`. time_created: type: string format: date-time minLength: 0 maxLength: 100 description: >- The date and time when processing for the payout began, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). sender_batch_header: $ref: '#/components/schemas/payout_sender_batch_header' description: The original payout header, as provided by the payment sender. required: - batch_status - payout_batch_id - sender_batch_header definitions-link_description_list: type: array description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). readOnly: true items: $ref: '#/components/schemas/link_description' minItems: 1 maxItems: 15000 error_details_list: type: array description: An array of additional details about the error. items: $ref: '#/components/schemas/error_details-2' link_description_list: type: array description: >- An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: '#/components/schemas/link_description' payout_item_request: type: object title: Payout Item description: The sender-created payout to a recipient. properties: recipient_type: type: string description: >- The recipient type. Value is:
If the sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value. minLength: 0 maxLength: 13 pattern: ^.*$ amount: $ref: '#/components/schemas/currency' description: The currency and amount to pay the receiver. note: type: string description: >- The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters. minLength: 0 maxLength: 4000 pattern: ^.*$ receiver: type: string description: >- The receiver of the payment. Corresponds to the `recipient_type` value in the request. Max value of up to 127 single-byte characters. minLength: 0 maxLength: 127 pattern: ^.*$ sender_item_id: type: string description: >- The sender-specified ID number. Tracks the payout in an accounting system. minLength: 0 maxLength: 63 pattern: ^.*$ recipient_wallet: type: string description: The recipient wallet. default: PAYPAL minLength: 0 maxLength: 36 pattern: ^.*$ alternate_notification_method: $ref: '#/components/schemas/alternate_notification_method' description: >- Captures additional notification modes to reach out to the receiver regarding this payment. notification_language: $ref: '#/components/schemas/language' description: >- The language in which to show the payout recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account. application_context: $ref: '#/components/schemas/application_context' description: >- Metadata for accepting additional information from merchants to Venmo. purpose: $ref: '#/components/schemas/purpose_enum' description: The purpose of the transaction. required: - amount - receiver batch_enum: title: Batch status description: The payouts status. type: string x-enumDescriptions: - value: DENIED description: >- Your payout requests were denied, so they were not processed. Check the error messages to see any steps necessary to fix these issues. - value: PENDING description: Your payout requests were received and will be processed soon. - value: PROCESSING description: Your payout requests were received and are now being processed. - value: SUCCESS description: >- Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions. - value: CANCELED description: >- The payouts file that was uploaded through the PayPal portal was cancelled by the sender. minLength: 1 maxLength: 36 pattern: ^[0-9A-Z_]+$ enum: - DENIED - PENDING - PROCESSING - SUCCESS - CANCELED payout_sender_batch_header: type: object title: Payout Sender Batch Header description: The sender-provided header for a payout request. properties: sender_batch_id: type: string description: >- The sender-specified ID number. Tracks the payout in an accounting system.
Note:

PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.

If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

minLength: 0 maxLength: 256 pattern: ^.*$ recipient_type: $ref: '#/components/schemas/recipient_enum' email_subject: type: string description: >- The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string with a maximum length of 255 single-byte characters. minLength: 0 maxLength: 255 pattern: ^.*$ email_message: type: string description: >- The email message that PayPal sends when the payout item completes. The message is the same for all recipients. minLength: 0 maxLength: 1000 pattern: ^.*$ link_description: type: object title: Link Description description: >- The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information. required: - href - rel properties: href: type: string description: >- The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. rel: type: string description: >- The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH error_details-2: title: Error Details type: object description: The error details. Required for client-side `4XX` errors. properties: field: type: string description: >- The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors. value: type: string description: The value of the field that caused the error. location: type: string description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. default: body issue: type: string description: The unique, fine-grained application-level error code. description: type: string description: >- The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value. required: - issue currency: type: object title: Currency description: >- The currency and amount for a financial transaction, such as a balance or payment due. properties: currency: type: string description: >- The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). value: type: string description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). required: - currency - value alternate_notification_method: type: object title: Alternate Notification Method description: >- Captures additional notification modes to reach out to the receiver regarding this payment. properties: phone: $ref: '#/components/schemas/phone' description: The mobile phone number of the receiver. language: type: string description: >- The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/). format: ppaas_common_language_v3 maxLength: 10 minLength: 2 pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$ application_context: type: object title: Application Context description: Metadata for Venmo transactions. properties: social_feed_privacy: type: string default: PRIVATE description: >- This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to `PRIVATE` if left blank. minLength: 1 maxLength: 15 pattern: ^.*$ holler_url: type: string description: >- Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151. format: uri minLength: 1 maxLength: 1000 deprecated: true logo_url: type: string description: >- Link to a logo that displays as the sender's profile image in the recipient's Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000. format: uri minLength: 0 maxLength: 1000 purpose_enum: type: string title: Purpose description: The purpose of the transaction. minLength: 1 maxLength: 40 pattern: ^[A-Z0-9_]+$ x-enumDescriptions: - value: AWARDS description: Awards payouts. - value: PRIZES description: Prizes payouts. - value: DONATIONS description: Donation payouts. - value: GOODS description: Payouts for goods sold. - value: SERVICES description: Payouts for services provided. - value: REBATES description: Rebate payouts. - value: CASHBACK description: Cashback payouts. - value: DISCOUNTS description: Discount payouts. - value: NON_GOODS_OR_SERVICES description: Payouts for any non-goods or services. enum: - AWARDS - PRIZES - DONATIONS - GOODS - SERVICES - REBATES - CASHBACK - DISCOUNTS - NON_GOODS_OR_SERVICES recipient_enum: title: Recipient type description: The ID type that identifies the payment receiver. type: string x-enumDescriptions: - value: EMAIL description: >- An unencrypted email. Value is a string of up to 127 single-byte characters. - value: PHONE description: An unencrypted phone number. - value: PAYPAL_ID description: An encrypted PayPal account number. minLength: 1 maxLength: 36 pattern: ^[0-9A-Z_]+$ enum: - EMAIL - PHONE - PAYPAL_ID phone: type: object title: Phone description: >- The phone number in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). properties: country_code: type: string description: >- The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: type: string description: >- The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ extension_number: type: string description: The extension number. minLength: 1 maxLength: 15 pattern: ^[0-9]{1,15}?$ required: - country_code - national_number securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token scopes: https://uri.paypal.com/payments/payouts: Payout to a list of recipients. https://uri.paypal.com/services/payments/payouts-item/reverse: For reversing a completed payout item. https://uri.paypal.com/services/payments/payout-applications/status: For retrieving payouts application status https://uri.paypal.com/services/payments/payout-applications/update-status: For updating payouts application status ````