openapi: 3.2.0 info: title: Invoices description: Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide. version: 2.12.0 servers: - url: https://api-m.sandbox.paypal.com description: PayPal API Sandbox tags: - name: accounting-sync description: This section contains invoicing APIs related to accounting sync. - name: bulk-sync-invoices-accounting-sync description: Use the /accounting-invoices-batch resource to bulk sync invoices with accounting software. - name: customer-feedbacks description: Use the /customer-feedbacks resource to create and retrieve feedbacks specific to merchants. - name: insights description: Use the /insights resource to generate reports and analytics on invoice data, including aging reports showing payment status by time periods. - name: invoice-notification description: Use the /email-status-feedback resource to post the status update against invoicing emails. - name: invoicing-multi-tenancy description: This section contains api to get the tenant config details. - name: invoicing-themes description: Use the /themes resource to create, update and get details of themes related to merchants. - name: search-enhancement description: This section contains the list of api, used to power invoicing search based on Index Organised Table(s). - name: account-closure description: Use the /cancel-user-records resource to cancel open records for a user and /get-user-record-count to get count of open records. - name: auto-reminder-configuration description: Use the auto-reminder-configuration to setup, suspend, resume and edit auto reminder configuration for invoices. - name: batch-tasks description: Use the /batch-tasks resource to create, delete and retrieve batch related tasks. - name: conditional-rules description: This section contains api's related to conditional rules. - name: connections description: Use the `accounting-sync/merchants/connections` resource to get active connections list. - name: estimates description: Use the /estimate resource to create, update, and send estimates. - name: invoice-connection-details description: Use the `accounting-sync/invoices/{id}/connections` resource to get active connections list. - name: invoice-payment-attempt description: This section contains api's related to invoice payment attempt. - name: invoices description: Use the `/invoices` resource to create, update, and send invoices and invoice reminders. To manage invoices, you can also list invoices, show details for invoices, delete draft invoices, and cancel sent invoices. You can also record payments for invoices to mark them as fully or partially paid, or record refunds for invoices to mark them as fully or partially refunded. You can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone. - name: invoicing-product-features description: This section contains the list of invoicing-product-features related api's. - name: merchant-config description: Use the `/merchant-config` resource to create, update and show details of merchant configuration. - name: payment-methods description: Use the payment-methods resource to create, update and get details of payment methods related to merchants/invoice. - name: recurring-invoices description: Use the `/recurring-invoices` resource to create, manage, and retrieve recurring invoice series. A recurring invoices automatically generates and sends invoices to customers on a scheduled basis according to a defined billing frequency and payment plan. To manage recurring series, you can create draft series with invoice templates and billing schedules, activate series to begin automatic invoice generation, update series configuration, cancel active series, and search for existing series. Each series includes the invoice template, line items, billing frequency, payment terms, recipient information, and scheduling details. - name: search-invoices description: Use the `/search-invoices` resource to search for and list invoices that match search criteria. - name: stored-discounts description: Use the /stored-discounts resource to create and retrieve stored-discounts are specific to merchants - name: templates description: Use the `/templates` resource to create, list, show details for, update, and delete invoice templates. Use the `/templates` resource when you create a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.
Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. When you create an invoice, you can use the URI for that logo.
externalDocs: url: /docs/invoicing/v2/ paths: /v2/invoicing/invoices: get: operationId: invoices.list summary: List invoices description: Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: page description: The page number to be retrieved, for the list of items. So, a combination of `page=1` and `page_size=20` returns the first 20 invoices. A combination of `page=2` and `page_size=20` returns the next 20 invoices. in: query schema: type: integer minimum: 1 maximum: 1000 default: 1 - name: page_size description: The maximum number of invoices to return in the response. in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: total_required description: Indicates whether the to show total_pages and total_items in the response. in: query schema: type: boolean default: false - name: fields description: A comma-separated list of additional fields to return, if available. in: query schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists invoices with details. content: application/json: schema: $ref: "#/components/schemas/invoices" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: invoices_fetch_all_400: summary: Lists invoices - 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: e7c71c2e905fa details: - field: page_size value: "1000" location: query issue: INVALID_INTEGER_MAX_VALUE description: The integer value of a field is too large. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Lists invoices - 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. response_example: responses/400/content/application~1json/examples/invoices_fetch_all_400 post: operationId: invoices.create summary: Create draft invoice description: Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.
Note: The merchant that you specify in an invoice must have a PayPal account in good standing.
. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/invoice" examples: invoices_create: summary: Create Invoice description: Creates an invoice. value: detail: invoice_number: "#123" reference: deal-ref invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 order_details: "Order #12345 placed on January 15, 2023." project_details: Website redesign project for client XYZ Corp. service_details: Consulting services provided from Jan-Mar 2023. cancellation_policy: Services may be cancelled with 14-day notice. payment_terms: Payment due within 10 days of invoice date. return_policy: All sales are final. No returns accepted after 30 days. service_agreement: Services provided as per agreement dated Jan 1, 2023. tip_presets: - percent: "15" - percent: "20" - percent: "25" invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" discount: percent: "5" unit_of_measure: QUANTITY - name: Yoga t-shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" tax_note: Reduced tax rate discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" allow_tip: true tax_calculated_after_discount: true tax_inclusive: false show_additional_item_fields: true template_id: TEMP-19V05281TU309413B amount: breakdown: custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" discount: invoice_discount: percent: "5" settings: invoice_item_settings: - field_name: ITEM_DESCRIPTION display_preference: hidden: false - field_name: ITEM_DATE display_preference: hidden: true - field_name: ITEM_TAX display_preference: hidden: false - field_name: ITEM_DISCOUNT display_preference: hidden: false invoice_additional_settings: - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: false - field_name: REFERENCE display_preference: hidden: false invoice_policy_and_agreement_settings: - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false - field_name: PAYMENT_TERMS display_preference: hidden: false invoice_details_settings: - field_name: ORDER_DETAILS display_preference: hidden: false - field_name: PROJECT_DETAILS display_preference: hidden: true responses: "201": description: A successful request returns the HTTP `201 Created` status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation. content: application/json: schema: $ref: "#/components/schemas/invoice" examples: invoices_create: summary: Create Invoice description: Creates an invoice. value: id: INV2-Z56S-5LLA-Q52L-CPZ5 status: DRAFT detail: invoice_number: "#123" reference: deal-ref invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 order_details: "Order #12345 placed on January 15, 2023." project_details: Website redesign project for client XYZ Corp. service_details: Consulting services provided from Jan-Mar 2023. cancellation_policy: Services may be cancelled with 14-day notice. payment_terms: Payment due within 10 days of invoice date. return_policy: All sales are final. No returns accepted after 30 days. service_agreement: Services provided as per agreement dated Jan 1, 2023. tip_presets: - percent: "15" - percent: "20" - percent: "25" metadata: create_time: 2018-11-12T08:00:20Z recipient_view_url: https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5 invoicer_view_url: https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5 invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: https://example.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "3.27" tax_note: Reduced tax rate discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - name: Yoga T Shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" tax_note: Reduced tax rate discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" allow_tip: true allow_only_pay_by_bank: true tax_calculated_after_discount: true show_additional_item_fields: true tax_inclusive: false template_id: TEMP-19V05281TU309413B amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" tax_note: Reduced tax rate discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" due_amount: currency_code: USD value: "74.21" settings: invoice_item_settings: - field_name: ITEM_DESCRIPTION display_preference: hidden: false - field_name: ITEM_DATE display_preference: hidden: true - field_name: ITEM_TAX display_preference: hidden: false - field_name: ITEM_DISCOUNT display_preference: hidden: true links: - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send rel: send method: POST - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/update rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments rel: record-payment method: POST - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code rel: qr-code method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Create Invoice description: Creates an invoice. parameter_examples: - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_create response_example: responses/201/content/application~1json/examples/invoices_create /v2/invoicing/invoices/{invoice_id}/send: post: operationId: invoices.send summary: Send invoice description: Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:To suppress the merchant's email notification, set the `send_to_invoicer` body parameter to `false`. To send the invoice through a share link and not through PayPal, set the send_to_recipient parameter to false in the notification object. The send_to_recipient parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.
Notes:
tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice to send. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_send_post_send_notification_schedule: summary: Send Invoice with future issue date to Payer description: Sends an invoice, by ID, to the payer. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/notification" examples: invoices_send_post_send_notification_schedule: summary: Send Invoice with future issue date to Payer description: Sends an invoice, by ID, to the payer. value: send_to_invoicer: true responses: "200": description: A successful request returns the HTTP `200 OK` when the invoice issue date is current date. content: application/json: schema: $ref: "#/components/schemas/link_description" "202": description: The server has accepted the request and will execute it at a later time. content: application/json: schema: $ref: "#/components/schemas/link_description" examples: example: value: href: https://api-m.paypal.com/invoice/p#INV2-Z56S-5LLA-Q52L-CPZ5 rel: payer-view method: GET summary: 202 response example description: A sample 202 response for invoices.send. "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Send Invoice Notification - 404 Resource Not Found description: This code sample attempts to send a notification for an invoice, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link details: - field: invoice_id location: path value: INV2-333R-YUQL-YNNN-D7WF "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Send Invoice with future issue date to Payer description: Sends an invoice, by ID, to the payer. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_send_post_send_notification_schedule - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_send_post_send_notification_schedule /v2/invoicing/invoices/{invoice_id}/remind: post: operationId: invoices.remind summary: Send invoice reminder description: Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a `notification` object that defines the subject of the reminder and other details.
Notes:
. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice for which to send a reminder. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_send_reminder_notification: summary: Remind Payer to Pay Invoice description: Reminds the payer to pay an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/notification" examples: invoices_send_reminder_notification: summary: Remind Payer to Pay Invoice description: Reminds the payer to pay an invoice, by ID. value: send_to_invoicer: true additional_recipients: - customer-a@example.com - customer@example.com responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Send Reminder - 404 Resource Not Found description: This code sample attempts to send a reminder for an invoice, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link details: - field: invoice_id location: path value: INV2-333R-YUQL-YNNN-D7WF "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "429": description: Too Many Requests. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Send Reminder - 429 Too many requests description: This code sample attempts to send a reminder for an invoice, by ID, but the request got blocked due to rate limiting. value: name: RATE_LIMIT_REACHED message: Too many requests. Blocked due to rate limiting. debug_id: e7931b94bbd3f details: - field: invoiceId value: INV2-333R-YUQL-YNNN-D7WF location: path issue: TOO_MANY_REQUESTS description: Too many requests. links: - href: https://developer.paypal.com/docs/api/invoicing/v2/#errors method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Remind Payer to Pay Invoice description: Reminds the payer to pay an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_send_reminder_notification - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_send_reminder_notification /v2/invoicing/invoices/{invoice_id}/cancel: post: operationId: invoices.cancel summary: Cancel sent invoice description: "Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails." tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice to cancel. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_cancel: summary: Cancel Invoice description: Cancels an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/notification" examples: invoices_cancel: summary: Cancel Invoice description: Cancels an invoice, by ID. value: send_to_invoicer: true send_to_recipient: true additional_recipients: - user@example.com responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Cancel Invoice - 404 Not Found Response description: This code sample attempts to cancel an invoice, by ID, but the request fails because the specified resource does not exist. value: debug_id: e50a003b5a9af links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link message: The specified resource does not exist. name: RESOURCE_NOT_FOUND "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Cancel Invoice description: Cancels an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_cancel - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_cancel /v2/invoicing/invoices/{invoice_id}/payments: post: operationId: invoices.payments summary: Record payment for invoice description: Records a payment for the invoice. If no payment is due, the invoice is marked as `PAID`. Otherwise, the invoice is marked as `PARTIALLY PAID`. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice to mark as paid. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_payments_record: summary: Record Payment for Invoice description: Records a payment for an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/payment_detail" examples: invoices_payments_record: summary: Record Payment for Invoice description: Records a payment for an invoice, by ID. value: method: BANK_TRANSFER payment_date: 2018-05-01 amount: currency_code: USD value: "10.00" responses: "200": description: A successful request returns the HTTP `200 Created` status code and a reference to the recorded payment. content: application/json: schema: $ref: "#/components/schemas/payment_reference" examples: invoices_payments_record: summary: Record Payment for Invoice description: Records a payment for an invoice, by ID. value: payment_id: EXTR-86F38350LX4353815 "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Cancel Recorded Payment - 404 Not Found description: This code sample attempts to cancel a recorded payment, by ID, but the request fails because the specified resource does not exist. value: debug_id: 4de1642ef13a7 links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link message: The specified resource does not exist. name: RESOURCE_NOT_FOUND "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Record Payment for Invoice description: Records a payment for an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_payments_record - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_payments_record response_example: responses/200/content/application~1json/examples/invoices_payments_record /v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}: delete: operationId: invoices.payments-delete summary: Delete external payment description: Deletes an external payment, by invoice ID and transaction ID. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice from which to delete an external payment transaction. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_payment_delete: summary: Delete External Payment description: Deletes an external payment for an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - name: transaction_id description: The ID of the external payment transaction to delete. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_payment_delete: summary: Delete External Payment description: Deletes an external payment for an invoice, by ID. value: EXTR-86F38350LX4353815 - $ref: "#/components/parameters/authorization" responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Delete External Payment - 404 Resource Not Found - Invalid Payment Transaction ID description: This code sample attempts to delete an external payment, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: delete details: - field: payment_id location: path value: EXTR-2LG703375E477444T "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Delete External Payment description: Deletes an external payment for an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_payment_delete - parameters/@name=='transaction_id'/examples/invoices_payment_delete - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/invoices/{invoice_id}/refunds: post: operationId: invoices.refunds summary: Record refund for invoice description: Records a refund for the invoice. If all payments are refunded, the invoice is marked as `REFUNDED`. Otherwise, the invoice is marked as `PARTIALLY REFUNDED`. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice to mark as refunded. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_refunds_record: summary: Record Refund for Invoice description: Records a refund for an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/refund_detail" examples: invoices_refunds_record: summary: Record Refund for Invoice description: Records a refund for an invoice, by ID. value: method: BANK_TRANSFER refund_date: 2018-05-21 amount: currency_code: USD value: "5.00" responses: "200": description: A successful request returns the HTTP `200 Created` status code and a reference to the recorded refund. content: application/json: schema: $ref: "#/components/schemas/refund_reference" examples: invoices_refunds_record: summary: Record Refund for Invoice description: Records a refund for an invoice, by ID. value: refund_id: EXTR-2LG703375E477444T "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Cancel Recorded Refund - 404 Not Found description: This code sample attempts to cancel a recorded refund, by ID, but the request fails because the specified resource does not exist. value: debug_id: d20c2b8d8f41c links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link message: The specified resource does not exist. name: RESOURCE_NOT_FOUND "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Record Refund for Invoice description: Records a refund for an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_refunds_record - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_refunds_record response_example: responses/200/content/application~1json/examples/invoices_refunds_record /v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}: delete: operationId: invoices.refunds-delete summary: Delete external refund description: Deletes an external refund, by invoice ID and transaction ID. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice from which to delete the external refund transaction. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_refunds_delete_delete_external_refund: summary: Delete External Refund for Invoice description: Deletes an external refund for an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - name: transaction_id description: The ID of the external refund transaction to delete. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: example: value: EXTR-2LG703375E477444T summary: Example transaction_id description: The ID of the external refund transaction to delete. - $ref: "#/components/parameters/authorization" responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Delete External Refund - 404 Resource Not Found - Invalid Refund Transaction ID description: This code sample attempts to delete an external refund, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: delete details: - field: invoice_id location: path value: INV2-333R-YUQL-YNNN-D7WF "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Delete External Refund for Invoice description: Deletes an external refund for an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_refunds_delete_delete_external_refund - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/invoices/{invoice_id}/generate-qr-code: post: operationId: invoices.generate-qr-code summary: Generate QR code description: Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must create an invoice and send an invoice to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice for which to generate a QR code. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_generate_qr_code: summary: Generate QR Code for Invoice description: Generates a QR code for an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/qr_config" examples: invoices_generate_qr_code: summary: Generate QR Code for Invoice description: Generates a QR code for an invoice, by ID. value: width: 400 height: 400 responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the QR code as a PNG image. "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Generate QR Code - 400 Bad Request description: This code sample attempts to generate a QR code for an invoice, but the request fails because it is not valid. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: 4c1000043769f links: - href: https://developer.paypal.com/docs/api/invoicing/#errors rel: information_link "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Generate QR Code - 404 Resource Not Found - Invalid ID description: This code sample attempts to generate a QR code, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link details: - field: invoice_id location: path value: INV2-333R-YUQL-YNNN-D7WF "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Generate QR Code for Invoice description: Generates a QR code for an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_generate_qr_code - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_generate_qr_code /v2/invoicing/generate-next-invoice-number: post: operationId: invoicing.generate-next-invoice-number summary: Generate invoice number description: Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after `INVOICE-1234` is `INVOICE-1235`. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/fetchtype" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the next invoice number. content: application/json: schema: $ref: "#/components/schemas/invoice_number" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: invoicing_generate-next-invoice-number_post_get_next_invoice_number_400: summary: 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: d075e1e8e0733 details: - field: fetch_id location: body description: 'Cannot deserialize value of type `java.lang.Boolean` from String "duplicate": only "true" or "false" recognized at line:2, column:18' links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. parameter_examples: - parameters/@name=='Authorization'/examples/bearer response_example: responses/400/content/application~1json/examples/invoicing_generate-next-invoice-number_post_get_next_invoice_number_400 /v2/invoicing/invoices/{invoice_id}: get: operationId: invoices.get summary: Show invoice details description: Shows details for an invoice, by ID. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: invoice_id description: The ID of the invoice for which to show details. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: example: value: INV2-Z56S-5LLA-Q52L-CPZ5 summary: Example invoice_id description: The ID of the invoice for which to show details. - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows invoice details. content: application/json: schema: $ref: "#/components/schemas/invoice" examples: invoices_get: summary: Show Invoice Details description: Shows details for an invoice, by ID. value: id: INV2-Z56S-5LLA-Q52L-CPZ5 status: DRAFT detail: invoice_number: "#123" reference: deal-ref invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 order_details: "Order #12345 placed on January 15, 2023." project_details: Website redesign project for client XYZ Corp. service_details: Consulting services provided from Jan-Mar 2023. cancellation_policy: Services may be cancelled with 14-day notice. payment_terms: Payment due within 10 days of invoice date. return_policy: All sales are final. No returns accepted after 30 days. service_agreement: Services provided as per agreement dated Jan 1, 2023. tip_presets: - percent: "15" - percent: "20" - percent: "25" metadata: create_time: 2018-11-12T08:00:20Z recipient_view_url: https://www.paypal.com/invoice/p/#Z56S5LLAQ52LCPZ5 invoicer_view_url: https://www.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5 invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: https://example.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" tax_note: Reduced tax rate amount: currency_code: USD value: "3.27" discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - name: Yoga T Shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" allow_tip: true allow_only_pay_by_bank: true tax_calculated_after_discount: true tax_inclusive: false show_additional_item_fields: false template_id: TEMP-19V05281TU309413B has_conditional_rule: true amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" due_amount: currency_code: USD value: "74.21" settings: invoice_item_settings: - field_name: ITEM_DESCRIPTION display_preference: hidden: false - field_name: ITEM_DATE display_preference: hidden: true - field_name: ITEM_TAX display_preference: hidden: false - field_name: ITEM_DISCOUNT display_preference: hidden: true invoice_additional_settings: - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: true - field_name: REFERENCE display_preference: hidden: false invoice_policy_and_agreement_settings: - field_name: PAYMENT_TERMS display_preference: hidden: false - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false invoice_details_settings: - field_name: ORDER_DETAILS display_preference: hidden: true - field_name: PROJECT_DETAILS display_preference: hidden: false - field_name: SERVICE_DETAILS display_preference: hidden: false links: - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send rel: send method: POST - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments rel: record-payment method: POST - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code rel: qr-code method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Show Invoice Details description: This code sample attempts to show details for an invoice, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 13baa436f527b links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Show Invoice Details description: Shows details for an invoice, by ID. parameter_examples: - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/invoices_get put: operationId: invoices.update summary: Fully update invoice description: Fully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates.
Notes:
. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the invoice to update. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_update: summary: Update Invoice description: Updates an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - name: send_to_recipient description: Indicates whether to send the invoice update notification to the recipient. in: query schema: type: boolean default: true - name: send_to_invoicer description: Indicates whether to send the invoice update notification to the merchant. in: query schema: type: boolean default: true - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/invoice" examples: invoices_update: summary: Update Invoice description: Updates an invoice, by ID. value: id: INV2-C82X-JNN9-Y6S5-CNXW status: DRAFT detail: invoice_number: "#123" reference: deal-refernce-update invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 order_details: "Updated order #12345 details from Jan 15, 2023." project_details: Updated website redesign project for XYZ Corp - added mobile optimization. service_details: Additional consulting services Jan-Apr 2023. cancellation_policy: "Updated: Services may be cancelled with 30-day notice." payment_terms: "Updated: Payment due within 15 days of invoice date." return_policy: "Updated: All sales are final. No returns accepted after 15 days." service_agreement: "Updated: Services provided as per revised agreement dated Feb 1, 2023." tip_presets: - percent: "15" - percent: "20" - percent: "25" invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" tax_note: Reduced tax rate amount: currency_code: USD value: "3.27" discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - name: Yoga t-shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" allow_tip: true tax_calculated_after_discount: true tax_inclusive: false show_additional_item_fields: true template_id: TEMP-19V05281TU309413B amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" settings: invoice_item_settings: - field_name: ITEM_DESCRIPTION display_preference: hidden: false - field_name: ITEM_DATE display_preference: hidden: true - field_name: ITEM_TAX display_preference: hidden: false - field_name: ITEM_DISCOUNT display_preference: hidden: true invoice_additional_settings: - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: false - field_name: REFERENCE display_preference: hidden: true invoice_policy_and_agreement_settings: - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false - field_name: PAYMENT_TERMS display_preference: hidden: false - field_name: CANCELLATION_POLICY display_preference: hidden: false invoice_details_settings: - field_name: SERVICE_DETAILS display_preference: hidden: false responses: "200": description: A successful request returns the HTTP `200 OK` status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation. content: application/json: schema: $ref: "#/components/schemas/invoice" examples: invoices_update: summary: Update Invoice description: Updates an invoice, by ID. value: id: INV2-C82X-JNN9-Y6S5-CNXW status: DRAFT detail: invoice_number: "#123" reference: deal-refernce-update invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 order_details: "Updated order #12345 details from Jan 15, 2023." project_details: Updated website redesign project for XYZ Corp - added mobile optimization. service_details: Additional consulting services Jan-Apr 2023. cancellation_policy: "Updated: Services may be cancelled with 30-day notice." payment_terms: "Updated: Payment due within 15 days of invoice date." return_policy: "Updated: All sales are final. No returns accepted after 15 days." service_agreement: "Updated: Services provided as per revised agreement dated Feb 1, 2023." tip_presets: - percent: "15" - percent: "20" - percent: "25" metadata: create_time: 2018-11-12T08:00:20Z recipient_view_url: https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5 invoicer_view_url: https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5 invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: https://example.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "3.27" discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - name: Yoga t-shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" allow_tip: true allow_only_pay_by_bank: true tax_calculated_after_discount: true show_additional_item_fields: true tax_inclusive: false template_id: TEMP-19V05281TU309413B amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" due_amount: currency_code: USD value: "74.21" settings: invoice_item_settings: - field_name: ITEM_DESCRIPTION display_preference: hidden: false - field_name: ITEM_DATE display_preference: hidden: true - field_name: ITEM_TAX display_preference: hidden: false - field_name: ITEM_DISCOUNT display_preference: hidden: false links: - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send rel: send method: POST - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/update rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: delete method: DELETE "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Update Invoice description: This code sample attempts to update an invoice, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: bd425f623f414 links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: replace "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "429": description: Too Many Requests. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Update Invoice - 429 Too many requests description: This code sample attempts to update an invoice, by ID, but the request got blocked due to rate limiting. value: name: RATE_LIMIT_REACHED message: Too many requests. Blocked due to rate limiting. debug_id: e7931b94bbd3f details: - field: invoiceId value: INV2-C82X-JNN9-Y6S5-CNXW location: path issue: TOO_MANY_REQUESTS description: Too many requests. links: - href: https://developer.paypal.com/docs/api/invoicing/v2/#errors method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Update Invoice description: Updates an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_update - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_update response_example: responses/200/content/application~1json/examples/invoices_update delete: operationId: invoices.delete summary: Delete invoice description: Deletes a draft or scheduled invoice, by ID. Deletes invoices in the draft or scheduled state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: invoice_id description: The ID of the draft invoice to delete. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: invoices_delete: summary: Delete Invoice description: Deletes an invoice, by ID. value: INV2-Z56S-5LLA-Q52L-CPZ5 - $ref: "#/components/parameters/authorization" responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Delete Invoice description: This code sample attempts to delete an invoice, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 471435cf878a4 links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: delete "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Delete Invoice description: Deletes an invoice, by ID. parameter_examples: - parameters/@name=='invoice_id'/examples/invoices_delete - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/search-invoices: post: operationId: invoices.search-invoices summary: Search for invoices description: Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria. tags: - search-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: page description: The page number to be retrieved, for the list of items. So, a combination of `page=1` and `page_size=20` returns the first 20 invoices. A combination of `page=2` and `page_size=20` returns the next 20 invoices. in: query schema: type: integer minimum: 1 maximum: 1000 default: 1 examples: invoices_search_search: summary: Search for Invoices description: Searches for invoices that match search criteria. value: 1 - name: page_size description: The page size for the search results. in: query schema: type: integer minimum: 1 maximum: 100 default: 20 examples: invoices_search_search: summary: Search for Invoices description: Searches for invoices that match search criteria. value: 1 - name: total_required description: Indicates whether the to show total_pages and total_items in the response. in: query schema: type: boolean default: false examples: invoices_search_search: summary: Search for Invoices description: Searches for invoices that match search criteria. value: true - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/search_data" examples: invoices_search_search: summary: Search for Invoices description: Searches for invoices that match search criteria. value: total_amount_range: lower_amount: currency_code: USD value: "50.00" upper_amount: currency_code: USD value: "50.00" invoice_date_range: start: 2018-06-01 end: 2018-06-21 responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the invoices that match the search criteria. content: application/json: schema: $ref: "#/components/schemas/invoices" examples: invoices_search_search: summary: Search for Invoices description: Searches for invoices that match search criteria. value: total_items: 6 total_pages: 1 items: - id: INV2-Z56S-5LLA-Q52L-CPZ5 status: DRAFT detail: invoice_number: "#123" reference: deal-ref invoice_date: 2018-11-12 currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: 2018-11-22 metadata: create_time: 2018-11-12T08:00:20Z recipient_view_url: https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5 invoicer_view_url: https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5 invoicer: email_address: merchant@example.com primary_recipients: - billing_info: email_address: bill-me@example.com amount: currency_code: USD value: "74.21" links: - href: https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 rel: self method: GET links: - href: https://api-m.paypal.com/v2/invoicing/invoices?page=2&page_size=10&total_required=true rel: next method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Search for Invoices description: Searches for invoices that match search criteria. parameter_examples: - parameters/@name=='page'/examples/invoices_search_search - parameters/@name=='total_required'/examples/invoices_search_search - parameters/@name=='page_size'/examples/invoices_search_search - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/invoices_search_search response_example: responses/200/content/application~1json/examples/invoices_search_search /v2/invoicing/templates: get: operationId: templates.list summary: List templates description: Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template. tags: - templates security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: fields description: The fields to return in the response. Value is `all` or `none`. To return only the template name, ID, and default attributes, specify `none`. in: query schema: type: string minLength: 1 maxLength: 2147483647 pattern: ^([Aa][Ll][Ll]|[Nn][Oo][Nn][Ee])$ default: all - name: page description: The page number to be retrieved, for the list of templates. So, a combination of `page=1` and `page_size=20` returns the first 20 templates. A combination of `page=2` and `page_size=20` returns the next 20 templates. in: query schema: type: integer minimum: 1 maximum: 1000 default: 1 - name: page_size description: The maximum number of templates to return in the response. in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists invoices. content: application/json: schema: $ref: "#/components/schemas/templates" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: templates_list_400: summary: List Templates - 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: 249cd3ba562bc details: - field: page_size value: "1000" location: query issue: INVALID_INTEGER_MAX_VALUE description: The integer value of a field is too large. links: - href: https://api-m.paypal.com/v2/invoicing/templates?page_size=1000 rel: self method: POST "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: List Templates - 400 Bad Request description: This sample returns a 400 Bad Request response when the request contains invalid parameters or malformed data. response_example: responses/400/content/application~1json/examples/templates_list_400 post: operationId: templates.create summary: Create template description: Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.
tags: - templates security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/template" examples: templates_create: summary: Create Template description: Creates a template. value: description: Template description default_template: true template_info: configuration: tax_calculated_after_discount: true show_additional_item_fields: false tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" detail: reference: deal-ref note: Thank you for your business. currency_code: USD terms_and_conditions: No refunds after 30 days. memo: This is a long contract attachments: - id: Screen Shot 2018-11-23 at 16.45.01.png reference_url: https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE payment_term: term_type: NET_10 service_agreement: This agreement covers the terms of the provided consulting services. tip_presets: - percent: "10" - percent: "15" - percent: "20" invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: MOBILE additional_info: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US additional_recipients: - inform-me@example.com items: - name: Yoga Mat description: new watch quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: name: Sales Tax percent: "7.25" discount: percent: "5" unit_of_measure: QUANTITY - name: Yoga T Shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" tax_note: Reduced tax rate discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY amount: currency_code: USD value: "74.21" breakdown: custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" discount: invoice_discount: percent: "5" settings: template_item_settings: - field_name: items.date display_preference: hidden: true - field_name: items.discount display_preference: hidden: false - field_name: items.tax display_preference: hidden: false - field_name: items.description display_preference: hidden: false - field_name: items.quantity display_preference: hidden: true template_subtotal_settings: - field_name: custom display_preference: hidden: false - field_name: discount display_preference: hidden: false - field_name: shipping display_preference: hidden: false template_invoice_details_settings: - field_name: ORDER_DETAILS display_preference: hidden: false - field_name: PROJECT_DETAILS display_preference: hidden: true - field_name: SERVICE_DETAILS display_preference: hidden: true template_policy_and_agreement_settings: - field_name: CANCELLATION_POLICY display_preference: hidden: true - field_name: PAYMENT_TERMS display_preference: hidden: true - field_name: RETURN_POLICY display_preference: hidden: true - field_name: SERVICE_AGREEMENT display_preference: hidden: true - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false template_additional_settings: - field_name: REFERENCE display_preference: hidden: false - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: false unit_of_measure: QUANTITY standard_template: false responses: "201": description: A successful request returns the HTTP `201 Created` status code. A JSON response body that shows template details is returned if you set prefer=return=representation. content: application/json: schema: $ref: "#/components/schemas/template" examples: templates_create: summary: Create Template description: Creates a template. value: id: TEMP-19V05281TU309413B name: reference-temp description: Template description default_template: true template_info: configuration: tax_calculated_after_discount: true show_additional_item_fields: false tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" detail: reference: deal-ref note: Thank you for your business. currency_code: USD terms_and_conditions: No refunds after 30 days. memo: This is a long contract attachments: - id: Screen Shot 2018-11-23 at 16.45.01.png reference_url: https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE payment_term: term_type: NET_10 tip_presets: - percent: "10" - percent: "15" - percent: "20" metadata: create_time: 2018-12-03T03:38:46z invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: MOBILE additional_info: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US additional_recipients: - inform-me@example.com items: - id: ITEM-9R873787D1610780X name: Yoga Mat description: new watch quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: id: TAX-9R873787D1610780X name: Sales Tax percent: "7.25" amount: currency_code: USD value: "3.27" discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - id: ITEM-4XD34145EH4061035 name: Yoga T Shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: id: TAX-4XD34145EH4061035 name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" settings: template_item_settings: - field_name: items.date display_preference: hidden: true - field_name: items.discount display_preference: hidden: false - field_name: items.tax display_preference: hidden: false - field_name: items.description display_preference: hidden: false - field_name: items.quantity display_preference: hidden: true template_subtotal_settings: - field_name: custom display_preference: hidden: false - field_name: discount display_preference: hidden: false - field_name: shipping display_preference: hidden: false template_invoice_details_settings: - field_name: ORDER_DETAILS display_preference: hidden: false - field_name: PROJECT_DETAILS display_preference: hidden: true - field_name: SERVICE_DETAILS display_preference: hidden: true template_policy_and_agreement_settings: - field_name: CANCELLATION_POLICY display_preference: hidden: true - field_name: PAYMENT_TERMS display_preference: hidden: true - field_name: RETURN_POLICY display_preference: hidden: true - field_name: SERVICE_AGREEMENT display_preference: hidden: true - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false template_additional_settings: - field_name: REFERENCE display_preference: hidden: false - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: false unit_of_measure: QUANTITY standard_template: false links: - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: replace method: PUT "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Create Template description: Creates a template. parameter_examples: - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/templates_create response_example: responses/201/content/application~1json/examples/templates_create /v2/invoicing/templates/{template_id}: get: operationId: templates.get summary: Show template details description: Shows details for a template, by ID. tags: - templates security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: template_id description: The ID of the template for which to show details. in: path required: true schema: type: string minLength: 1 maxLength: 22 pattern: ^(@default|TEMP-[A-Z0-9]{17})$ examples: templates_get: summary: Show Template Details description: Shows details for a template, by ID. value: TEMP-19V05281TU309413B - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows template details. content: application/json: schema: $ref: "#/components/schemas/template" examples: templates_get: summary: Show Template Details description: Shows details for a template, by ID. value: id: TEMP-19V05281TU309413B name: reference-temp description: Template description default_template: true template_info: configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true show_additional_item_fields: false partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "20.00" detail: reference: deal-ref currency_code: USD note: Thank you for your business. terms_and_conditions: No refunds after 30 days. memo: This is a long contract attachments: - id: Screen Shot 2018-11-23 at 16.45.01.png reference_url: https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE payment_term: term_type: NET_10 tip_presets: - percent: "10" - percent: "15" - percent: "20" service_agreement: This agreement covers the terms of the provided consulting services. metadata: create_time: 2018-12-03T03:38:46z invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: merchant@example.com phones: - country_code: "001" national_number: "4085551234" phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US email_address: bill-me@example.com phones: - country_code: "001" national_number: "4884551234" phone_type: MOBILE additional_info: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: "98765" country_code: US additional_recipients: - inform-me@example.com items: - id: ITEM-9R873787D1610780X name: Yoga Mat description: new watch quantity: "1" unit_amount: currency_code: USD value: "50.00" tax: id: TAX-9R873787D1610780X name: Sales Tax percent: "7.25" tax_note: Reduced tax rate amount: currency_code: USD value: "3.27" discount: percent: "5" amount: currency_code: USD value: "2.5" unit_of_measure: QUANTITY - id: ITEM-4XD34145EH4061035 name: Yoga T Shirt quantity: "1" unit_amount: currency_code: USD value: "10.00" tax: id: TAX-4XD34145EH4061035 name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.34" discount: amount: currency_code: USD value: "5.00" unit_of_measure: QUANTITY amount: currency_code: USD value: "74.21" breakdown: item_total: currency_code: USD value: "60.00" custom: label: Packing Charges amount: currency_code: USD value: "10.00" shipping: amount: currency_code: USD value: "10.00" tax: name: Sales Tax percent: "7.25" amount: currency_code: USD value: "0.73" discount: item_discount: currency_code: USD value: "-7.50" invoice_discount: percent: "5" amount: currency_code: USD value: "-2.63" tax_total: currency_code: USD value: "4.34" settings: template_item_settings: - field_name: items.date display_preference: hidden: true - field_name: items.discount display_preference: hidden: false - field_name: items.tax display_preference: hidden: false - field_name: items.description display_preference: hidden: false - field_name: items.quantity display_preference: hidden: true template_subtotal_settings: - field_name: custom display_preference: hidden: false - field_name: discount display_preference: hidden: false - field_name: shipping display_preference: hidden: false template_invoice_details_settings: - field_name: ORDER_DETAILS display_preference: hidden: false - field_name: PROJECT_DETAILS display_preference: hidden: true - field_name: SERVICE_DETAILS display_preference: hidden: true template_policy_and_agreement_settings: - field_name: CANCELLATION_POLICY display_preference: hidden: true - field_name: PAYMENT_TERMS display_preference: hidden: true - field_name: RETURN_POLICY display_preference: hidden: true - field_name: SERVICE_AGREEMENT display_preference: hidden: true - field_name: TERMS_AND_CONDITIONS display_preference: hidden: false template_additional_settings: - field_name: REFERENCE display_preference: hidden: false - field_name: ATTACHMENT display_preference: hidden: false - field_name: MEMO display_preference: hidden: false unit_of_measure: QUANTITY standard_template: false links: - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B rel: replace method: PUT "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: templates_get_404_not_active: summary: Show Template Details - 404 Not Found description: This code sample attempts to show details for a template, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 14e7d6da0230e links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Show Template Details description: Shows details for a template, by ID. parameter_examples: - parameters/@name=='template_id'/examples/templates_get - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/templates_get put: operationId: templates.update summary: Fully update template description: Fully updates a template, by ID. In the JSON request body, include a complete `template` object. This call does not support partial updates. tags: - templates security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: template_id description: The ID of the template for which to show details. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/template" responses: "200": description: A successful request returns the HTTP `200 OK` status code. A JSON response body that shows template details is returned if you set prefer=return=representation. content: application/json: schema: $ref: "#/components/schemas/template" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Update Template - 404 Not Found description: This code sample attempts to complete a full update of a template, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: eb2b60eeb68bb links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: replace details: - field: template_id location: path value: TEMP-6YL6786487972583X "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Update Template - 404 Not Found description: This code sample attempts to complete a full update of a template, by ID, but the request fails because the specified resource does not exist. parameter_examples: - parameters/@name=='template_id'/examples/template_with_theme_templates_update_with_theme - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/template_with_theme_templates_update_with_theme response_example: responses/404/content/application~1json/examples/generic delete: operationId: templates.delete summary: Delete template description: Deletes a template, by ID. tags: - templates security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite parameters: - name: template_id description: The ID of the template to delete. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^.*$ examples: templates_delete: summary: Delete Template description: Deletes a template, by ID. value: TEMP-19V05281TU309413B - $ref: "#/components/parameters/authorization" responses: "204": $ref: "#/components/responses/204_response" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: templates_delete_404_resource_deleted: summary: Delete Template - 404 Not Found description: This code sample attempts to delete a template, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 515a02fde4bac links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: delete templates_delete_404: summary: Delete Template - 404 Not Found description: This code sample attempts to delete a template, by ID, but the request fails because the specified resource does not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: eb2b60eeb68bb links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: delete details: - field: template_id location: path value: TEMP-6YL6786487972583X "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Delete Template description: Deletes a template, by ID. parameter_examples: - parameters/@name=='template_id'/examples/templates_delete - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/invoices/{id}/conditional-rules/{conditional_rule_id}: get: operationId: get-invoice-conditional-rule-by-id summary: Retrieve the conditional rule details for an Invoice description: Retrieve the conditional rule details for an Invoice. tags: - conditional-rules security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: id description: The ID of the invoice for which to show details. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ examples: example: value: INV2-S884-EJT6-73AU-QF4C summary: Example id description: The ID of the invoice for which to show details. - name: conditional_rule_id description: The conditional rule ID of the invoice for which to retrieve details. in: path required: true schema: type: string minLength: 39 maxLength: 39 pattern: ^CR-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{12}$ examples: example: value: CR-11FF-A725-27C6999C-A699-33CD614E75EC summary: Example conditional_rule_id description: The conditional rule ID of the invoice for which to retrieve details. - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows conditional rules details for a particular invoice. content: application/json: schema: $ref: "#/components/schemas/conditional_rule" examples: conditional_rule_conditional_rules_get_by_conditional_rule_id: summary: Get conditional rule by id for the Invoice description: Retrieve the conditional rule associated with a specific invoice based on the conditional rule id. value: conditional_rule_id: CR-11FF-A725-27C6999C-A699-33CD614E75EC conditional_rule_type: EARLY_PAYMENT_DISCOUNT conditional_rule_value_type: PERCENT conditional_rule_value: "5" rule_expiry_terms: rule_expiry_condition: SEVEN_DAYS_AFTER_ISSUE_DATE condition_rule_end_date: 2025-03-12 created_time: 2025-01-29T10:15:30Z updated_time: 2025-01-29T10:15:30Z links: - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: replace method: PUT - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: delete method: DELETE - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C rel: up method: GET - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: self method: GET_BY_CR_ID "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Get conditional Rule for the invoice - 404 Not Found description: This code sample attempts to retrieve conditional rules for an invoice, by invoice ID, but the request fails because either the invoice or the associated rules do not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 13baa436f527b links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Get conditional rule by id for the Invoice description: Retrieve the conditional rule associated with a specific invoice based on the conditional rule id. parameter_examples: - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/conditional_rule_conditional_rules_get_by_conditional_rule_id put: operationId: update-conditional-rule summary: Fully update conditional rule description: Fully updates conditional rule for the invoice. In the JSON request body, include a complete `conditional rule` object. This call does not support partial updates. tags: - conditional-rules security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - name: id description: The ID of the invoice for which to update the conditional rule associated with it. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ examples: example: value: INV2-S884-EJT6-73AU-QF4C summary: Example id description: The ID of the invoice for which to update the conditional rule associated with it. - name: conditional_rule_id description: The conditional rule ID to update. in: path required: true schema: type: string minLength: 39 maxLength: 39 pattern: ^CR-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{12}$ examples: example: value: CR-11FF-A725-27C6999C-A699-33CD614E75ED summary: Example conditional_rule_id description: The conditional rule ID to update. - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/conditional_rule" examples: example: value: conditional_rule_type: EARLY_PAYMENT_DISCOUNT conditional_rule_value_type: PERCENT conditional_rule_value: "10" rule_expiry_terms: rule_expiry_condition: SEVEN_DAYS_AFTER_ISSUE_DATE condition_rule_end_date: 2025-03-12 summary: Fully update conditional rule description: A sample request body for update-conditional-rule. responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the updated conditional rule. content: application/json: schema: $ref: "#/components/schemas/conditional_rule" examples: conditional_rules_put: summary: Updating conditional rules description: Updating conditional rules for an invoice with conditional parameters. value: conditional_rule_id: CR-11FF-A725-27C6999C-A699-33CD614E75EC conditional_rule_type: EARLY_PAYMENT_DISCOUNT conditional_rule_value_type: PERCENT conditional_rule_value: "10" rule_expiry_terms: rule_expiry_condition: SEVEN_DAYS_AFTER_ISSUE_DATE condition_rule_end_date: 2025-03-12 created_time: 2025-01-29T10:15:30Z updated_time: 2025-01-29T10:15:30Z links: - href: v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: self method: GET - href: v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: delete method: DELETE "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Updating conditional rules - 404 Not Found description: Updating conditional rules for an invoice with conditional parameters, but the request fails because either the invoice or the associated rules do not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 13baa436f527b links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Updating conditional rules description: Updating conditional rules for an invoice with conditional parameters. response_example: responses/200/content/application~1json/examples/conditional_rules_put delete: operationId: delete-invoice-conditional-rule summary: Delete the conditional rule details from the Invoice description: Delete the conditional rule associated with a given Invoice ID and conditional rule ID. tags: - conditional-rules security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - name: id description: The ID of the invoice for which to delete the conditional rule associated with it. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ - name: conditional_rule_id description: The conditional rule ID of the invoice for which to delete the detail. in: path required: true schema: type: string minLength: 39 maxLength: 39 pattern: ^CR-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{12}$ - $ref: "#/components/parameters/authorization" responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: conditional_rules_delete_conditional_rules_delete_400: summary: Deactivate the Conditional Rule for the invoice - 400 Bad Request Response description: This code sample attempts to deactivate the conditional rules for an invoice, but fails due to bad input. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: 80931aae87961 details: - issue: INVALID_PARAMETER_VALUE description: The value of a field is invalid. field: conditional_rule_id value: CR-11FF-A725-27C6999C-A699-33CD614E75EC location: path links: - href: https://developer.paypal.com/docs/api/invoicing/#errors rel: information_link method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Deactivate the Conditional Rule for the invoice - 404 Not Found description: This code sample attempts to deactivate conditional rules for an invoice, by invoice ID, but the request fails because either the invoice or the associated rules do not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 13baa436f527b links: - href: https://developer.paypal.com/docs/api/invoicing/#errors rel: information_link method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Deactivate the Conditional Rule for the invoice - 400 Bad Request Response description: This code sample attempts to deactivate the conditional rules for an invoice, but fails due to bad input. response_example: responses/400/content/application~1json/examples/conditional_rules_delete_conditional_rules_delete_400 /v2/invoicing/invoices/{id}/conditional-rules: get: operationId: get-invoice-conditional-rules summary: Retrieves all conditional rules for a given Invoice. description: Retrieves all conditional rules details for an Invoice. The response includes a list of conditional rules associated with the invoice, along with their details such as rule type, value, expiry terms etc. tags: - conditional-rules security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read parameters: - name: id description: The ID of the invoice for which to show details. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ examples: example: value: INV2-S884-EJT6-73AU-QF4C summary: Example id description: The ID of the invoice for which to show details. - $ref: "#/components/parameters/authorization" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows conditional rules details for a particular invoice. content: application/json: schema: $ref: "#/components/schemas/conditional_rules" examples: example: value: rules: - conditional_rule_id: CR-11FF-A725-27C6999C-A699-33CD614E75ED conditional_rule_type: EARLY_PAYMENT_DISCOUNT conditional_rule_value_type: PERCENT conditional_rule_value: "5" rule_expiry_terms: rule_expiry_condition: SEVEN_DAYS_AFTER_ISSUE_DATE condition_rule_end_date: 2025-03-12 created_time: 2025-01-29T10:15:30Z updated_time: 2025-01-29T10:15:30Z links: - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75ED rel: self method: GET - rel: self href: https://api.paypal.com/v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C method: GET - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75ED rel: update method: PUT - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75ED rel: delete method: DELETE - conditional_rule_id: CR-11FF-A725-27C6999C-A699-33CD614E75EC conditional_rule_type: AUTO_CANCEL rule_expiry_terms: rule_expiry_condition: SPECIFIC_DATE condition_rule_end_date: 2025-03-12 created_time: 2025-01-29T10:15:30Z updated_time: 2025-01-29T10:15:30Z links: - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: self method: GET - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: update method: PUT - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75EC rel: delete method: DELETE links: - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules rel: self method: GET - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C rel: invoice method: GET summary: 200 response example description: A sample 200 response for get-invoice-conditional-rules. "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Get Conditional Rules for the invoice - 404 Not Found description: This code sample attempts to retrieve conditional rules for an invoice, by invoice ID, but the request fails because either the invoice or the associated rules do not exist. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 13baa436f527b links: - href: https://developer.paypal.com/docs/limited-release/invoicing/#errors rel: information_link method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Get conditional rules for the Invoice description: Retrieves the conditional rules associated with a specific invoice. post: operationId: create-conditional-rules summary: Create conditional rules description: This will create the conditional rules for the invoice. tags: - conditional-rules security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - name: id description: The ID of the invoice for which the conditional rules are to be created for. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ - $ref: "#/components/parameters/authorization" - $ref: "#/components/parameters/paypal_request_id" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/conditional_rules" responses: "200": description: A successful request returns the HTTP `200 OK` status code. A JSON response body that shows conditional rules is returned. content: application/json: schema: $ref: "#/components/schemas/conditional_rules" examples: conditional_rule_conditional_rules_get: summary: Retrieving conditional rules for invoice description: Retrieves the conditional rules configured for an invoice. value: rules: - conditional_rule_id: CR-11FF-A725-27C6999C-A699-33CD614E75EC conditional_rule_type: EARLY_PAYMENT_DISCOUNT conditional_rule_value_type: PERCENT conditional_rule_value: "5" rule_expiry_terms: rule_expiry_condition: SEVEN_DAYS_AFTER_ISSUE_DATE condition_rule_end_date: 2025-03-12 created_time: 2025-01-29T10:15:30Z updated_time: 2025-01-29T10:15:30Z links: - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75E rel: self method: GET - href: /v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75E rel: update method: PUT - href: v2/invoicing/invoices/INV2-S884-EJT6-73AU-QF4C/conditional-rules/CR-11FF-A725-27C6999C-A699-33CD614E75E rel: delete method: DELETE "201": description: A successful request returns the HTTP `201 Created` status code. A JSON response body that shows conditional rules is returned. content: application/json: schema: $ref: "#/components/schemas/conditional_rules" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: conditional_rules_create_conditional_rules_create_400: summary: Creating conditional rules - 400 Bad Request Response description: Creating conditional rules for an invoice with conditional parameters, but fails due to bad input. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: 80931aae87961 details: - issue: INVALID_PARAMETER_VALUE description: The value of a field is invalid. field: /rules/0/rule_expiry_terms/rule_expiry_condition value: SEVENTY_DAYS_AFTER_ISSUE_DATE location: body links: - href: https://developer.paypal.com/docs/api/invoicing/#errors rel: information_link method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Creating conditional rules - 400 Bad Request Response description: Creating conditional rules for an invoice with conditional parameters, but fails due to bad input. response_example: responses/400/content/application~1json/examples/conditional_rules_create_conditional_rules_create_400 /v2/invoicing/recurring-invoices: post: operationId: recurring_invoices.create summary: Create a recurring invoice series description: Recurring invoices series that automatically generates and sends invoices to customers on a scheduled basis. The series includes the invoice template, billing frequency, payment terms, recipient information, line items and other invoice configuration. Once activated, invoices are sent according to the configured schedule until the series expires or is cancelled. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/recurring_series" examples: recurring_series_recurring_series_create: summary: Create recurring invoice series - Success response description: Successfully creates a recurring invoice series and returns the created series details. value: plan_detail: total_cycles: 6 frequency: interval_unit: MONTH interval_count: 1 start_series_date: 2026-01-19 recurring_info: detail: reference: "0001" currency_code: USD note: Thank you terms_and_conditions: Your terms and conditions memo: Gift pack category_code: SHIPPABLE payment_term: term_type: DUE_ON_RECEIPT primary_recipients: - billing_info: email_address: test@paypal.com items: - name: pen quantity: "1" unit_amount: currency_code: USD value: "12.00" unit_of_measure: QUANTITY configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "2.00" responses: "201": description: The recurring invoice series was successfully created. Returns the HTTP `201 CREATED` status code and a JSON response body containing the complete series details including the unique series ID, invoice template, billing frequency, payment terms, recipient information, line items, other invoice configuration and metadata. content: application/json: schema: $ref: "#/components/schemas/recurring_series" examples: recurring_series_recurring_series_create: summary: Create recurring invoice series - Success response description: Successfully creates a recurring invoice series. value: id: RI-9Y6699772R098892C status: DRAFT plan_detail: total_cycles: 1 frequency: interval_unit: MONTH interval_count: 1 start_series_date: 2026-01-20 completed_cycles: 0 recurring_info: detail: reference: "0001" currency_code: USD note: Thank you terms_and_conditions: Your terms and conditions memo: Gift pack category_code: SHIPPABLE payment_term: term_type: DUE_ON_RECEIPT primary_recipients: - billing_info: email_address: test@gmail.com items: - id: ITEM-69D690885J782781N name: pen quantity: "1" unit_amount: currency_code: USD value: "12.00" unit_of_measure: QUANTITY configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "2.00" template_id: TEMP-1B23377148371954V amount: breakdown: item_total: currency_code: USD value: "12.00" discount: invoice_discount: amount: currency_code: USD value: "0.00" item_discount: currency_code: USD value: "0.00" tax_total: currency_code: USD value: "0.00" currency_code: USD value: "12.00" metadata: create_time: 2026-01-20T09:55:09Z last_update_time: 2026-01-20T09:55:09Z links: - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C/cancel rel: cancel method: POST - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C/activate rel: activate method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Create recurring invoice series - Success response description: Successfully creates a recurring invoice series and returns the created series details. parameter_examples: - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/recurring_series_recurring_series_create /v2/invoicing/recurring-invoices/{id}: get: operationId: recurring_invoices.get summary: Get recurring invoice series details description: Get details for a recurring invoice series by ID. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the recurring series for which to retrieve details. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ examples: recurring_series_recurring_series_get: summary: Get recurring invoice series - Success response description: Successfully retrieves the details of a recurring invoice series by ID. value: RI-9Y6699772R098892C responses: "200": description: The recurring invoice series details were successfully retrieved. Returns the HTTP `200 OK` status code and a JSON response body containing the complete series details including the unique series ID, invoice template, billing frequency, payment terms, recipient information, line items, metadata and other invoice configuration. content: application/json: schema: $ref: "#/components/schemas/recurring_series" examples: recurring_series_recurring_series_get: summary: Get recurring invoice series - Success response description: Successfully retrieves the details of a recurring invoice series by ID. value: id: RI-9Y6699772R098892C status: DRAFT plan_detail: total_cycles: 1 frequency: interval_unit: MONTH interval_count: 1 start_series_date: 2026-01-20 completed_cycles: 0 recurring_info: detail: reference: "0001" currency_code: USD note: Thank you terms_and_conditions: Your terms and conditions memo: Gift pack category_code: SHIPPABLE payment_term: term_type: DUE_ON_RECEIPT primary_recipients: - billing_info: email_address: test@gmail.com items: - id: ITEM-69D690885J782781N name: pen quantity: "1" unit_amount: currency_code: USD value: "12.00" unit_of_measure: QUANTITY configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "2.00" template_id: TEMP-1B23377148371954V amount: breakdown: item_total: currency_code: USD value: "12.00" discount: invoice_discount: amount: currency_code: USD value: "0.00" item_discount: currency_code: USD value: "0.00" tax_total: currency_code: USD value: "0.00" currency_code: USD value: "12.00" metadata: create_time: 2026-01-20T09:55:09Z last_update_time: 2026-01-20T09:55:09Z links: - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C/cancel rel: cancel method: POST - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-9Y6699772R098892C/activate rel: activate method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Get recurring invoice series - Invalid series ID description: Request fails when the specified recurring series ID is not found. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-9Y6699772R098892D location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Get recurring invoice series - Success response description: Successfully retrieves the details of a recurring invoice series by ID. parameter_examples: - parameters/@name=='id'/examples/recurring_series_recurring_series_get - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/recurring_series_recurring_series_get put: operationId: recurring_invoices.update summary: Update recurring invoice series details description: Update recurring invoice series details by ID. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the recurring series to be updated. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ examples: recurring_series_active_recurring_series_update: summary: Update already active recurring invoice series - Success response description: Successfully updates a recurring invoice series and returns the updated series details. value: RI-5VG36420NF0175035 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/recurring_series" examples: recurring_series_active_recurring_series_update: summary: Update already active recurring invoice series - Success response description: Successfully updates a recurring invoice series and returns the updated series details. value: plan_detail: total_cycles: 8 frequency: interval_unit: MONTH interval_count: 2 start_series_date: 2026-01-19 recurring_info: detail: reference: "0002" currency_code: USD note: Thank you terms_and_conditions: Your terms and conditions memo: Gift pack category_code: SHIPPABLE payment_term: term_type: DUE_ON_RECEIPT primary_recipients: - billing_info: email_address: test@paypal.com items: - name: pen quantity: "2" unit_amount: currency_code: USD value: "12.00" unit_of_measure: QUANTITY configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "2.00" responses: "200": description: The recurring invoice series was successfully updated. Returns the HTTP `200 OK` status code and a JSON response body containing the complete series details including the unique series ID, invoice template, billing frequency, payment terms, recipient information, line items, metadata and other invoice configuration. content: application/json: schema: $ref: "#/components/schemas/recurring_series" examples: recurring_series_active_recurring_series_update: summary: Update already active recurring invoice series - Success response description: Successfully updates a recurring invoice series and returns the updated series details. value: id: RI-9Y6699772R098892C status: ACTIVE plan_detail: total_cycles: 8 frequency: interval_unit: MONTH interval_count: 1 start_series_date: 2026-01-19 completed_cycles: 0 recurring_info: detail: reference: "0001" currency_code: USD note: Thank you terms_and_conditions: Your terms and conditions memo: Gift pack category_code: SHIPPABLE payment_term: term_type: DUE_ON_RECEIPT primary_recipients: - billing_info: email_address: test@paypal.com items: - id: ITEM-3LD558161T864042C name: pen quantity: "1" unit_amount: currency_code: USD value: "12.00" unit_of_measure: QUANTITY configuration: tax_calculated_after_discount: true tax_inclusive: false allow_tip: true partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: "2.00" template_id: TEMP-1B23377148371954V amount: breakdown: item_total: currency_code: USD value: "12.00" discount: invoice_discount: amount: currency_code: USD value: "0.00" item_discount: currency_code: USD value: "0.00" tax_total: currency_code: USD value: "0.00" currency_code: USD value: "12.00" metadata: create_time: 2026-01-20T05:17:06Z last_update_time: 2026-01-20T05:17:06Z links: - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201 rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201 rel: delete method: DELETE - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201 rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201/cancel rel: cancel method: POST - href: https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201/activate rel: activate method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Update recurring invoice series - Invalid recurring series ID description: Request fails when the specified recurring series not exists. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-9Y6699772R09889EE location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Update already active recurring invoice series - Success response description: Successfully updates a recurring invoice series and returns the updated series details. parameter_examples: - parameters/@name=='id'/examples/recurring_series_active_recurring_series_update - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/recurring_series_active_recurring_series_update response_example: responses/200/content/application~1json/examples/recurring_series_active_recurring_series_update delete: operationId: recurring_invoices.delete summary: Delete recurring invoice series description: Delete recurring invoice series by ID. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the recurring series to be deleted. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ examples: example: value: RI-9Y6699772R098892C summary: Example id description: The ID of the recurring series to be deleted. responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Delete recurring invoice series - Invalid series ID description: Request fails when the specified recurring series ID is not found. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-9Y6699772R098892D location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Delete recurring invoice series - Success response description: Successfully deleted recurring invoice series by ID. parameter_examples: - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/recurring-invoices/{id}/activate: post: operationId: recurring_invoices.activate summary: Activate recurring invoice series description: Activate recurring invoice series by ID, Once activated system will start sending invoices based on the schedule. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the recurring series to activate. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ examples: example: value: RI-9Y6699772R098892C summary: Example id description: The ID of the recurring series to activate. responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Activate recurring invoice series - Invalid series ID description: Request fails when the specified recurring series ID is not found. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-9Y6699772R098892D location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Activate recurring invoice series - Success response description: Successfully activated recurring invoice series by ID. parameter_examples: - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/recurring-invoices/{id}/cancel: post: operationId: recurring_invoices.cancel summary: Cancel an active recurring invoice series description: Cancel recurring invoice series by ID. tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the recurring series to cancel. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ examples: example: value: RI-9Y6699772R098892C summary: Example id description: The ID of the recurring series to cancel. responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Cancel recurring invoice series - Invalid series ID description: Request fails when the specified recurring series ID is not found. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-9Y6699772R098892D location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Cancel recurring invoice series - Success response description: Successfully cancelled recurring invoice series by ID. parameter_examples: - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/setup-reminders: post: operationId: auto-reminder-configuration.setup summary: Setup auto reminder configuration. description: "Initializes the auto reminder configuration for a merchant account. This controller resource accepts an optional array of reminder configuration objects. A maximum of two reminder types are supported: BEFORE_DUE and AFTER_DUE.

Implementation behavior:

Default configuration values:

Note: After successful execution, both reminder configurations (BEFORE_DUE and AFTER_DUE) will exist for the merchant account. If reminder configurations already exist for the merchant account, the request fails with a 422 Unprocessable Entity error.
" tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/invoice_auto_reminder_config_setup" examples: auto_reminder_configuration_auto_reminder_configuration_setup: summary: Setup auto reminder configuration - Success description: "Successfully initializes the default auto reminder configuration for the merchant account. This request creates two reminder configurations: one for reminders sent before the invoice due date (BEFORE_DUE) and one for reminders sent after the due date (AFTER_DUE). The response includes the complete configuration details for both reminder types, including their unique IDs, timing intervals, repetition settings, and current status. Each configuration is created in an ACTIVE state and includes HATEOAS links for managing the configuration." value: configurations: - type: BEFORE_DUE interval: unit: DAY value: 2 repetition: 1 notification: send_to_invoicer: false - type: AFTER_DUE interval: unit: DAY value: 2 repetition: 2 notification: send_to_invoicer: false responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body. content: application/json: schema: $ref: "#/components/schemas/invoice_reminder_configurations" examples: auto_reminder_configuration_auto_reminder_configuration_setup: summary: Setup auto reminder configuration - Success description: "Successfully initializes the default auto reminder configuration for the merchant account. This request creates two reminder configurations: one for reminders sent before the invoice due date (BEFORE_DUE) and one for reminders sent after the due date (AFTER_DUE). The response includes the complete configuration details for both reminder types, including their unique IDs, timing intervals, repetition settings, and current status. Each configuration is created in an ACTIVE state and includes HATEOAS links for managing the configuration." value: configurations: - id: RC-239531651S471944P type: BEFORE_DUE status: ACTIVE interval: unit: DAY value: 2 repetition: 1 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/resume rel: resume method: POST - id: RC-19C40543NJ101123L type: AFTER_DUE status: ACTIVE interval: unit: DAY value: 2 repetition: 2 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L/resume rel: resume method: POST links: - href: https://api-m.paypal.com/v2/invoicing/reminders rel: collection method: GET "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Setup auto reminder configuration - Success description: "Successfully initializes the default auto reminder configuration for the merchant account. This request creates two reminder configurations: one for reminders sent before the invoice due date (BEFORE_DUE) and one for reminders sent after the due date (AFTER_DUE). The response includes the complete configuration details for both reminder types, including their unique IDs, timing intervals, repetition settings, and current status. Each configuration is created in an ACTIVE state and includes HATEOAS links for managing the configuration." parameter_examples: - parameters/@name=='Authorization'/examples/bearer request_body_example: requestBody/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_setup response_example: responses/200/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_setup /v2/invoicing/reminders: get: operationId: auto-reminder-configuration.get-all summary: Get all invoice auto reminder configuration. description: Retrieves all auto reminder configurations associated with the merchant account. This operation returns both BEFORE_DUE and AFTER_DUE reminder configurations, regardless of their current status (ACTIVE or INACTIVE). Each configuration includes complete details such as timing intervals, repetition counts, notification preferences, status information, creation and update timestamps, and HATEOAS links for managing the configurations. tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: type description: Filters reminder configurations by reminder type. If not provided, all reminder configurations (BEFORE_DUE and AFTER_DUE) are returned. in: query required: false schema: type: string enum: - BEFORE_DUE - AFTER_DUE oneOf: - type: string enum: - BEFORE_DUE description: Represents the auto reminder configuration for invoices prior to their due date. - type: string enum: - AFTER_DUE description: Represents the auto reminder configuration for invoices after their due date. responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body. content: application/json: schema: $ref: "#/components/schemas/invoice_reminder_configurations" examples: auto_reminder_configuration_auto_reminder_configuration_get_all: summary: Get all auto reminder configurations - Success description: Successfully retrieves all auto reminder configurations associated with the merchant account. The response returns both BEFORE_DUE and AFTER_DUE reminder configurations, regardless of their current status (ACTIVE or INACTIVE). Each configuration includes comprehensive details such as timing intervals, repetition counts, notification preferences, status information, and HATEOAS links for managing the configurations. This endpoint is useful for reviewing all reminder settings and their current operational state. value: configurations: - id: RC-239531651S471944P type: BEFORE_DUE status: ACTIVE interval: unit: DAY value: 2 repetition: 1 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/resume rel: resume method: POST - id: RC-19C40543NJ101123L type: AFTER_DUE status: ACTIVE interval: unit: DAY value: 2 repetition: 2 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-19C40543NJ101123L/resume rel: resume method: POST links: - href: https://api-m.paypal.com/v2/invoicing/reminders rel: self method: GET "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Get all auto reminder configurations - Success description: Successfully retrieves all auto reminder configurations associated with the merchant account. The response returns both BEFORE_DUE and AFTER_DUE reminder configurations, regardless of their current status (ACTIVE or INACTIVE). Each configuration includes comprehensive details such as timing intervals, repetition counts, notification preferences, status information, and HATEOAS links for managing the configurations. This endpoint is useful for reviewing all reminder settings and their current operational state. parameter_examples: - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_get_all /v2/invoicing/reminders/{id}: get: operationId: auto-reminder-configuration.get summary: Retrieve an invoice auto reminder configuration description: Retrieves the details of a specific auto reminder configuration by providing its unique configuration ID. This operation returns comprehensive configuration information including the reminder type (BEFORE_DUE or AFTER_DUE), current status, timing interval settings, repetition count, notification preferences, metadata with creation and last update timestamps, and HATEOAS links for performing operations on the configuration. tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the auto reminder configuration to be fetched. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^RC-[A-Z0-9]+$ examples: auto_reminder_configuration_auto_reminder_configuration_get: summary: Get auto reminder configuration - Success description: Successfully retrieves the details of a specific auto reminder configuration using its unique configuration ID. The response includes complete configuration information such as the reminder type (BEFORE_DUE or AFTER_DUE), current status, timing interval settings, repetition count, notification preferences, and metadata including creation and last update timestamps. The response also provides HATEOAS links for performing operations on this configuration, including retrieving, updating, suspending, and resuming the reminder settings. value: RC-239531651S471944P responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body. content: application/json: schema: $ref: "#/components/schemas/invoice_reminder_configuration" examples: auto_reminder_configuration_auto_reminder_configuration_get: summary: Get auto reminder configuration - Success description: Successfully retrieves the details of a specific auto reminder configuration using its unique configuration ID. The response includes complete configuration information such as the reminder type (BEFORE_DUE or AFTER_DUE), current status, timing interval settings, repetition count, notification preferences, and metadata including creation and last update timestamps. The response also provides HATEOAS links for performing operations on this configuration, including retrieving, updating, suspending, and resuming the reminder settings. value: id: RC-239531651S471944P type: BEFORE_DUE status: ACTIVE interval: unit: DAY value: 2 repetition: 1 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/resume rel: resume method: POST "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Get auto reminder configuration - Configuration not found description: The request fails with a 404 Not Found error when the specified reminder configuration ID does not exist in the system or has been deleted. Verify that the configuration ID is correct and that the configuration is accessible to the authenticated merchant. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RC-239531651S471944C location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Get auto reminder configuration - Success description: Successfully retrieves the details of a specific auto reminder configuration using its unique configuration ID. The response includes complete configuration information such as the reminder type (BEFORE_DUE or AFTER_DUE), current status, timing interval settings, repetition count, notification preferences, and metadata including creation and last update timestamps. The response also provides HATEOAS links for performing operations on this configuration, including retrieving, updating, suspending, and resuming the reminder settings. parameter_examples: - parameters/@name=='id'/examples/auto_reminder_configuration_auto_reminder_configuration_get - parameters/@name=='Authorization'/examples/bearer response_example: responses/200/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_get put: operationId: auto-reminder-configuration.update summary: Update invoice auto reminder configuration. description: Updates an existing auto reminder configuration by providing the configuration ID and the updated settings in the request body. This operation allows modification of reminder timing intervals, repetition counts, and notification preferences. Note that this performs a full update of the configuration, so all required fields must be included in the request. tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: Prefer description: The Prefer request header field is used to indicate that particular server behavior is preferred by the client but is not required for successful completion of the request. For example, the value 'return=representation' indicates that the client prefers that the API server include an entity representing the current state of the resource in the response to a successful request. in: header required: false schema: type: string minLength: 1 maxLength: 16000 pattern: ^.*$ examples: auto_reminder_configuration_auto_reminder_configuration_update: summary: Update auto reminder configuration - Success description: Successfully updates an existing auto reminder configuration by providing the configuration ID and the updated settings in the request body. This example demonstrates updating a BEFORE_DUE reminder configuration to send reminders 1 day before the invoice due date with 1 repetition. The request performs a full update of the configuration, so all fields must be included. The response returns the complete updated configuration with the new interval value, along with metadata showing the update timestamp and HATEOAS links for further operations. value: return=representation - name: id description: The ID of the auto reminder configuration to be updated. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^RC-[A-Z0-9]+$ examples: example: value: RC-239531651S471944P summary: Example id description: The ID of the auto reminder configuration to be updated. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/invoice_reminder_configuration" examples: auto_reminder_configuration_auto_reminder_configuration_update: summary: Update auto reminder configuration - Success description: Successfully updates an existing auto reminder configuration by providing the configuration ID and the updated settings in the request body. This example demonstrates updating a BEFORE_DUE reminder configuration to send reminders 1 day before the invoice due date with 1 repetition. The request performs a full update of the configuration, so all fields must be included. The response returns the complete updated configuration with the new interval value, along with metadata showing the update timestamp and HATEOAS links for further operations. value: type: BEFORE_DUE interval: unit: DAY value: 1 repetition: 1 responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body. A JSON response body that shows auto reminder configuration details if you set prefer=return=representation. content: application/json: schema: $ref: "#/components/schemas/invoice_reminder_configuration" examples: auto_reminder_configuration_auto_reminder_configuration_update: summary: Update auto reminder configuration - Success description: Successfully updates an existing auto reminder configuration by providing the configuration ID and the updated settings in the request body. This example demonstrates updating a BEFORE_DUE reminder configuration to send reminders 1 day before the invoice due date with 1 repetition. The request performs a full update of the configuration, so all fields must be included. The response returns the complete updated configuration with the new interval value, along with metadata showing the update timestamp and HATEOAS links for further operations. value: id: RC-239531651S471944P type: BEFORE_DUE status: ACTIVE interval: unit: DAY value: 1 repetition: 1 metadata: created_time: 2026-01-28T03:31:53Z updated_time: 2026-01-28T03:31:53Z notification: send_to_invoicer: false links: - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: self method: GET - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P rel: replace method: PUT - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/suspend rel: suspend method: POST - href: https://api-m.paypal.com/v2/invoicing/reminders/RC-239531651S471944P/resume rel: resume method: POST "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Update auto reminder configuration - Configuration not found description: The request fails with a 404 Not Found error when the specified reminder configuration ID does not exist in the system or has been deleted. Verify that the configuration ID is correct and that the configuration is accessible to the authenticated merchant. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RC-239531651S471944C location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Update auto reminder configuration - Success description: Successfully updates an existing auto reminder configuration by providing the configuration ID and the updated settings in the request body. This example demonstrates updating a BEFORE_DUE reminder configuration to send reminders 1 day before the invoice due date with 1 repetition. The request performs a full update of the configuration, so all fields must be included. The response returns the complete updated configuration with the new interval value, along with metadata showing the update timestamp and HATEOAS links for further operations. parameter_examples: - parameters/@name=='Authorization'/examples/bearer - parameters/@name=='Prefer'/examples/auto_reminder_configuration_auto_reminder_configuration_update request_body_example: requestBody/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_update response_example: responses/200/content/application~1json/examples/auto_reminder_configuration_auto_reminder_configuration_update /v2/invoicing/reminders/{id}/suspend: post: operationId: auto-reminder-configuration.suspend summary: Suspend invoice auto reminder configuration. description: Temporarily deactivates an active auto reminder configuration by marking it as inactive. This operation stops all scheduled reminder notifications without deleting the configuration. All configuration settings are preserved and can be reactivated at any time using the resume endpoint. This is useful for temporarily pausing reminders during holidays, business closures, or while making adjustments to reminder strategies. A configuration can only be suspended when it is currently in an active state. tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The unique identifier of the auto reminder configuration to be suspended. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^RC-[A-Z0-9]+$ examples: example: value: RC-239531651S471944P summary: Example id description: The unique identifier of the auto reminder configuration to be suspended. responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Suspend auto reminder configuration - Configuration not found description: The request fails with a 404 Not Found error when the specified reminder configuration ID does not exist in the system or has been deleted. Verify that the configuration ID is correct and that the configuration is accessible to the authenticated merchant. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RI-239531651S471944C location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Suspend auto reminder configuration - Success description: Successfully suspends an active auto reminder configuration, temporarily disabling automated reminder notifications without deleting the configuration. This request returns a 204 No Content status code upon successful completion. While suspended, the configuration will not trigger any scheduled reminders, but all settings are preserved and can be reactivated using the resume endpoint. This is useful for temporarily pausing reminders during holidays, business closures, or while making adjustments to reminder strategies. parameter_examples: - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/reminders/{id}/resume: post: operationId: auto-reminder-configuration.resume summary: Resume invoice auto reminder configuration. description: This operation activates the auto reminder configuration. When a suspended configuration is resumed, reminder notifications will be sent for invoices that have invoice-level auto-reminders enabled and still have future scheduled reminder dates. Invoices issued during the suspension period are eligible only if their reminder schedules remain valid. This applies only to invoices with auto-reminders enabled. If reminders were explicitly canceled for an invoice, no reminder notifications will be sent. tags: - auto-reminder-configuration security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The unique identifier of the auto reminder configuration to be reactivated. in: path required: true schema: type: string minLength: 20 maxLength: 20 pattern: ^RC-[A-Z0-9]+$ examples: example: value: RC-239531651S471944P summary: Example id description: The unique identifier of the auto reminder configuration to be reactivated. responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Resume auto reminder configuration - Configuration not found description: The request fails with a 404 Not Found error when the specified reminder configuration ID does not exist in the system or has been deleted. Verify that the configuration ID is correct and that the configuration is accessible to the authenticated merchant. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: RC-239531651S471944C location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Resume auto reminder configuration - Success description: Successfully reactivates a previously suspended auto reminder configuration, allowing automated reminder notifications to be sent again. This request returns a 204 No Content status code upon successful completion. Once resumed, the configuration becomes active and the system will evaluate pending invoices to schedule appropriate reminders based on the configuration settings. All previous configuration settings remain unchanged from when the configuration was suspended. Note that resuming does not retroactively send reminders that would have been sent during the suspension period. parameter_examples: - parameters/@name=='Authorization'/examples/bearer /v2/invoicing/invoices/{id}/cancel-reminders: post: operationId: invoices.cancel-reminders summary: Cancel auto reminders for an invoice. description: Cancels all scheduled automatic reminders for a specific invoice. This operation is permanent and cannot be reversed - once reminders are cancelled for an invoice, they cannot be re-enabled. The specified invoice will no longer receive automated reminder notifications, while other invoices continue to follow the active reminder configuration. This is typically used when a customer has requested no further reminders, payment arrangements have been made outside the system, or manual communication is preferred for sensitive situations. tags: - invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: id description: The ID of the invoice for which reminders have to be canceled. in: path required: true schema: type: string minLength: 24 maxLength: 24 pattern: ^INV2-[A-Z0-9-]+$ responses: "204": $ref: "#/components/responses/204_response" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: invoice_cancel_reminders_400: summary: Cancel auto reminders for invoice - Invalid invoice ID format description: The request fails with a 400 Bad Request error when the provided invoice ID has an invalid format or does not conform to the expected pattern. The invoice ID must follow the format INV2-XXXX-XXXX-XXXX-XXXX. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: b54c3ac13ea3c details: - field: id value: EST-3FEH-MNRP-UNHK-A9J8 location: path issue: INVALID_PARAMETER_SYNTAX description: The value of a field does not conform to the expected format. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "404": description: Not Found. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Cancel auto reminders for invoice - Invoice not found description: The request fails with a 404 Not Found error when the specified invoice ID does not exist in the system or has been deleted. Verify that the invoice ID is correct and that the invoice is accessible to the authenticated merchant. value: name: RESOURCE_NOT_FOUND message: The specified resource does not exist. debug_id: 3ea444214c04b details: - field: id value: INV2-3FEH-MNRP-UNHK-A9J9 location: path issue: INVALID_RESOURCE_ID description: The requested resource ID was not found. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Cancel auto reminders for invoice - Invalid invoice ID format description: The request fails with a 400 Bad Request error when the provided invoice ID has an invalid format or does not conform to the expected pattern. The invoice ID must follow the format INV2-XXXX-XXXX-XXXX-XXXX. response_example: responses/400/content/application~1json/examples/invoice_cancel_reminders_400 /v2/invoicing/search-recurring-invoices: post: operationId: recurring_invoices.search summary: Search recurring invoices series. description: "Endpoint to search recurring invoice series based on search criteria. Note: Users are able to search only for the past 3 years." tags: - recurring-invoices security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite - https://uri.paypal.com/services/invoicing/internal parameters: - $ref: "#/components/parameters/authorization" - name: page description: A non-zero integer representing the page of the results. in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 1 - name: page_size description: A non-negative, non-zero integer indicating the maximum number of results to return at one time. in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/recurring_series_search_data" responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the recurring invoices series that match the search criteria. content: application/json: schema: $ref: "#/components/schemas/multiple_recurring_series" "400": description: Invalid request. content: application/json: schema: $ref: "#/components/schemas/error" examples: recurring_series_search_recurring_series_search_400: summary: Search recurring invoices series - Bad Request response. description: Request fails due to invalid page size. value: name: INVALID_REQUEST message: Request is not well-formed, syntactically incorrect, or violates schema. debug_id: e7c71c2e905fa details: - field: page_size value: "1000" location: query issue: INVALID_INTEGER_MAX_VALUE description: The integer value of a field is too large. links: - href: https://developer.paypal.com/docs/api/invoicing/#errors method: GET "401": $ref: "#/components/responses/401_error_response" "403": $ref: "#/components/responses/403_error_response" "422": description: Unprocessable entity. content: application/json: schema: $ref: "#/components/schemas/error" "500": $ref: "#/components/responses/500_error_response" default: $ref: "#/components/responses/default_response" x-exampleFlows: - title: Search recurring invoices series - Bad Request response. description: Request fails due to invalid page size. parameter_examples: - parameters/@name=='Authorization'/examples/bearer response_example: responses/400/content/application~1json/examples/recurring_series_search_recurring_series_search_400 components: securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /api/oauth-proxy scopes: https://uri.paypal.com/services/invoicing/invoices/read: For Reading the invoice details. https://uri.paypal.com/services/invoicing/invoices/readwrite: For managing (Create, Update, Delete) invoice. https://uri.paypal.com/services/invoicing/internal: Manage invoice resource internal clients. schemas: standard_header_schema: title: Schema Object for standard headers description: Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers. type: string minLength: 1 maxLength: 16000 pattern: ^.*$ correlation_id: title: Correlation Id description: A correlation id used for debugging. type: string minLength: 1 maxLength: 100 pattern: ^.*$ link_description: title: Link Description description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. type: object required: - href - rel properties: href: 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. type: string minLength: 0 maxLength: 20000 pattern: ^.*$ rel: 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). type: string minLength: 0 maxLength: 100 pattern: ^.*$ method: description: The HTTP method required to make the related call. type: string enum: - CONNECT - DELETE - GET - HEAD - OPTIONS - PATCH - POST - PUT oneOf: - type: string enum: - CONNECT description: The HTTP CONNECT method. - type: string enum: - DELETE description: The HTTP DELETE method. - type: string enum: - GET description: The HTTP GET method. - type: string enum: - HEAD description: The HTTP HEAD method. - type: string enum: - OPTIONS description: The HTTP OPTIONS method. - type: string enum: - PATCH description: The HTTP PATCH method. - type: string enum: - POST description: The HTTP POST method. - type: string enum: - PUT description: The HTTP PUT method. error_details: title: Error Details description: The error details. Required for client-side `4XX` errors. type: object required: - issue properties: field: 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. type: string minLength: 0 maxLength: 10000 pattern: ^.*$ value: description: The value of the field that caused the error. type: string minLength: 0 maxLength: 100000 pattern: ^.*$ location: description: The location of the field that caused the error. type: string default: body enum: - body - header - path - query oneOf: - type: string enum: - body description: The field is in the request body. - type: string enum: - header description: The field is a header. - type: string enum: - path description: The field is a path parameter. - type: string enum: - query description: The field is a query parameter. issue: description: The unique, fine-grained application-level error code. type: string minLength: 0 maxLength: 100000 pattern: ^.*$ links: description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions. type: array minItems: 1 maxItems: 4 items: $ref: "#/components/schemas/link_description" description: 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. type: string minLength: 0 maxLength: 100000 pattern: ^.*$ error: title: Error description: The error details. type: object required: - name - message - debug_id properties: name: description: The human-readable, unique name of the error. type: string minLength: 0 maxLength: 10000 pattern: ^.*$ message: description: The message that describes the error. type: string minLength: 0 maxLength: 100000 pattern: ^.*$ debug_id: allOf: - $ref: "#/components/schemas/correlation_id" - description: The PayPal internal ID. Used for correlation purposes. details: description: An array of additional details about the error. type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_details" links: description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/link_description" invoice_status: title: invoice_status description: The status of the invoice. type: string enum: - DRAFT - SENT - SCHEDULED - PAID - MARKED_AS_PAID - CANCELLED - REFUNDED - PARTIALLY_PAID - PARTIALLY_REFUNDED - MARKED_AS_REFUNDED - UNPAID - PAYMENT_PENDING - AUTO_CANCELLED - PAID_EXTERNAL - REFUNDED_EXTERNAL - SHARED oneOf: - type: string enum: - DRAFT description: The invoice is in draft state. It is not yet sent to the payer. - type: string enum: - SENT description: The invoice has been sent to the payer. The payment is awaited from the payer. - type: string enum: - SCHEDULED description: The invoice is scheduled on a future date. It is not yet sent to the payer. - type: string enum: - PAID description: The payer has paid for the invoice. - type: string enum: - MARKED_AS_PAID description: The invoice is marked as paid by the invoicer. - type: string enum: - CANCELLED description: The invoice has been cancelled by the invoicer. - type: string enum: - REFUNDED description: The invoice has been refunded by the invoicer. - type: string enum: - PARTIALLY_PAID description: The payer has partially paid for the invoice. - type: string enum: - PARTIALLY_REFUNDED description: The invoice has been partially refunded by the invoicer. - type: string enum: - MARKED_AS_REFUNDED description: The invoice is marked as refunded by the invoicer. - type: string enum: - UNPAID description: The invoicer is yet to receive the payment from the payer for the invoice. - type: string enum: - PAYMENT_PENDING description: The invoicer is yet to receive the payment for the invoice. It is under pending review. - type: string enum: - AUTO_CANCELLED description: The invoice was automatically cancelled because the payment was not received within the specified timeframe. - type: string enum: - PAID_EXTERNAL description: The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means. - type: string enum: - REFUNDED_EXTERNAL description: The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow. - type: string enum: - SHARED description: The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal. currency_code: description: The [3-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 pattern: ^[\S\s]*$ date_time: description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
type: string minLength: 20 maxLength: 64 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ file_reference: title: File Reference description: The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or another custom store. type: object properties: id: description: The ID of the referenced file. type: string minLength: 1 maxLength: 255 pattern: ^.*$ reference_url: description: The reference URL for the file. type: string minLength: 1 maxLength: 2000 format: uri content_type: description: The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml). type: string minLength: 0 maxLength: 255 pattern: ^.*$ create_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the file was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). size: description: The size of the file, in bytes. type: string minLength: 0 maxLength: 100 pattern: ^[0-9]+$ detail: title: detail description: The details of the invoice like notes, terms and conditions, memo, attachments. type: object required: - currency_code properties: reference: description: The reference data. Includes a Purchase Order (PO) number. type: string minLength: 1 maxLength: 120 pattern: ^[\S\s]*$ currency_code: $ref: "#/components/schemas/currency_code" note: description: A note to the invoice recipient. Also appears on the invoice notification email. type: string minLength: 1 maxLength: 4000 pattern: ^[\S\s]*$ terms_and_conditions: description: The general terms of the invoice. Can include return or cancellation policy and other terms and conditions. type: string minLength: 1 maxLength: 4000 pattern: ^[\S\s]*$ memo: description: A private bookkeeping memo for the user. type: string minLength: 1 maxLength: 500 pattern: ^[\S\s]*$ attachments: description: An array of PayPal IDs for the files that are attached to an invoice. type: array minItems: 0 maxItems: 32767 items: allOf: - $ref: "#/components/schemas/file_reference" - title: attachment tip_preset: title: tip_preset description: Defines a tip option that can be presented to the customer as a percentage of the invoice total. **Note:** This preset represents a tip configuration where the percentage value is applied during checkout to calculate the tip amount. type: object properties: percent: description: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`.The tip percentage ranges from 0.00001 to 100.00000 inclusive and supports up to five decimal places. type: string minLength: 1 maxLength: 20 pattern: ^(([0-9]+)|(([0-9]+)?[.][0-9]+))$ examples: - "19.99" additional_detail: title: Additional Detail description: Additional business and descriptive details that can be associated with invoices, templates, and other resources. type: object allOf: - $ref: "#/components/schemas/detail" - type: object properties: tip_presets: description: Specifies the predefined tip options configured by the invoicer. These preset values are shown to customers at checkout as suggested tipping amounts, in addition to the option to enter a custom tip. type: array minItems: 1 maxItems: 3 items: $ref: "#/components/schemas/tip_preset" order_details: description: Order details information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ project_details: description: Project details information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ service_details: description: Service details information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ payment_terms: description: Payment terms information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ return_policy: description: Return policy information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ cancellation_policy: description: Cancellation policy information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ service_agreement: description: Service agreement information. type: string minLength: 1 maxLength: 2500 pattern: ^[\S\s]*$ date_no_time: description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years. type: string minLength: 10 maxLength: 10 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$ payment_term_type: title: payment_term_type description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days. type: string enum: - DUE_ON_RECEIPT - DUE_ON_DATE_SPECIFIED - NET_10 - NET_15 - NET_30 - NET_45 - NET_60 - NET_90 - NO_DUE_DATE oneOf: - type: string enum: - DUE_ON_RECEIPT description: The payment for the invoice is due upon receipt of the invoice. - type: string enum: - DUE_ON_DATE_SPECIFIED description: The payment for the invoice is due on the date specified in the invoice. - type: string enum: - NET_10 description: The payment for the invoice is due in 10 days. - type: string enum: - NET_15 description: The payment for the invoice is due in 15 days. - type: string enum: - NET_30 description: The payment for the invoice is due in 30 days. - type: string enum: - NET_45 description: The payment for the invoice is due in 45 days. - type: string enum: - NET_60 description: The payment for the invoice is due in 60 days. - type: string enum: - NET_90 description: The payment for the invoice is due in 90 days. - type: string enum: - NO_DUE_DATE description: The invoice has no payment due date. percentage: description: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`. type: string minLength: 0 maxLength: 500 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ money: title: Money description: The currency and amount for a financial transaction, such as a balance or payment due. type: object required: - currency_code - value properties: currency_code: $ref: "#/components/schemas/currency_code" value: description: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). type: string minLength: 0 maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ early_payment_discount: title: early_payment_discount description: The early payment discount for the invoice. If the payer pays before the discount end date, the specified discount is applied. type: object properties: discount_end_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The end date for the early payment discount, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. percent: allOf: - $ref: "#/components/schemas/percentage" - description: The early payment discount percentage value. amount: allOf: - $ref: "#/components/schemas/money" - description: The early payment discount amount value. is_applied: description: Indicates whether the particular rule is applied or not. type: boolean auto_cancellation: title: auto_cancellation description: The auto cancellation details for the invoice. If the payer does not pay by the specified date, the invoice is automatically cancelled. type: object properties: cancel_by_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The date by which the invoice is automatically cancelled if unpaid, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. is_applied: description: Indicates whether the particular rule is applied or not. type: boolean payment_term_conditional_rules: title: payment_term_conditional_rules description: The conditional rules associated with the payment term of the invoice. Includes early payment discount, late payment surcharge, and auto cancellation details. type: object properties: early_payment_discount: $ref: "#/components/schemas/early_payment_discount" auto_cancellation: $ref: "#/components/schemas/auto_cancellation" payment_term: title: payment_term description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days. type: object properties: term_type: $ref: "#/components/schemas/payment_term_type" conditional_rules: $ref: "#/components/schemas/payment_term_conditional_rules" invoice_payment_term: title: invoice_payment_term description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days. type: object allOf: - $ref: "#/components/schemas/payment_term" - type: object properties: due_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The date when the invoice payment is due, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. template_metadata: title: template_metadata description: The audit metadata. Captures all template actions on create and update. type: object properties: create_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the resource was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true created_by: description: The email address of the account that created the resource. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true last_update_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the resource was last edited, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_updated_by: description: The email address of the account that last edited the resource. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true invoice_creation_flow: title: invoice_creation_flow description: The frequency at which the invoice is sent: type: string enum: - MULTIPLE_RECIPIENTS_GROUP - BATCH - REGULAR_SINGLE oneOf: - type: string enum: - MULTIPLE_RECIPIENTS_GROUP description: The invoice sent to multiple recipients. - type: string enum: - BATCH description: The invoice sent as a batch. - type: string enum: - REGULAR_SINGLE description: The regular invoice sent to single recipient. metadata: title: metadata description: The audit metadata. Captures all invoicing actions on create, send, update, and cancel. type: object allOf: - $ref: "#/components/schemas/template_metadata" - type: object properties: cancel_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the resource was canceled, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true cancelled_by: description: The actor who canceled the resource. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true first_sent_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the resource was first sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_sent_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the resource was last sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_sent_by: description: The email address of the account that last sent the resource. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true created_by_flow: allOf: - $ref: "#/components/schemas/invoice_creation_flow" - description: The flow variation that created this invoice. readOnly: true recipient_view_url: description: The URL for the invoice payer view hosted on paypal.com. type: string minLength: 0 maxLength: 2147483647 format: uri readOnly: true invoicer_view_url: description: The URL for the invoice merchant view hosted on paypal.com. type: string minLength: 0 maxLength: 2147483647 format: uri readOnly: true invoice_detail: title: invoice_detail description: The details of the invoice. Includes invoice number, date, payment terms, and audit metadata. type: object allOf: - $ref: "#/components/schemas/additional_detail" - type: object properties: invoice_number: description: The invoice number. If omitted, an auto-incremented number from the last number is used. type: string minLength: 0 maxLength: 25 pattern: ^[\S\s]*$ invoice_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The invoice date as specificed by the sender, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Only UTC is supported in response. For example, *yyyy*-*MM*-*dd*T*z*. payment_term: allOf: - $ref: "#/components/schemas/invoice_payment_term" - description: The payment due date for the invoice. Value is either but not both term_type or due_date. metadata: allOf: - $ref: "#/components/schemas/metadata" - readOnly: true orthography: title: Orthography Type description: The orthography type based on the ISO 15924 names for scripts. Scipts are chosen based on [most widely used writing systems](https://www.worldatlas.com/articles/the-world-s-most-popular-writing-scripts.html). type: string enum: - Arab - Armn - Beng - Cans - Cyrl - Deva - Ethi - Geor - Grek - Gujr - Guru - Hani - Hebr - Java - Jpan - Kana - Khmr - Knda - Kore - Laoo - Latn - Mlym - Mong - Mymr - Orya - Sinh - Sund - Syrc - Taml - Telu - Thaa - Thai - Tibt - Yiii - Zyyy - Zzzz oneOf: - type: string enum: - Arab description: The Arabic language alphabet. - type: string enum: - Armn description: The Armenian alphabet. - type: string enum: - Beng description: The Bengali alphabet. Used in eastern India. - type: string enum: - Cans description: The Unified Canadian Aboriginal Syllabics alphabet. - type: string enum: - Cyrl description: The Slavic languages alphabet. Used in eastern Europe. - type: string enum: - Deva description: The Devanagari (Nagari) alphabet. - type: string enum: - Ethi description: The Ethiopic alphabet. - type: string enum: - Geor description: The Georgian (Mkhedruli and Mtavruli) alphabet. - type: string enum: - Grek description: The Greek alphabet. - type: string enum: - Gujr description: The Gujurati language alphabet. Used in western India. - type: string enum: - Guru description: The Gurmukhi alphabet. Used in the northern Indian state of Punjab. - type: string enum: - Hani description: The Han (Hanzi, Kanji, Hanja) alphabet. - type: string enum: - Hebr description: The Hebrew alphabet. - type: string enum: - Java description: The Javanese alphabet. - type: string enum: - Jpan description: The Japanese (alias for Han + Hiragana + Katakana) alphabet. - type: string enum: - Kana description: An angular form of Japanese writing for words of foreign origin. - type: string enum: - Khmr description: The Khmer alphabet. - type: string enum: - Knda description: The Kannada alphabet. Used in the southern Indian state of Karnataka. - type: string enum: - Kore description: Korean (alias for Hangul + Han). - type: string enum: - Laoo description: The Lao alphabet. - type: string enum: - Latn description: The Latin alphabet. - type: string enum: - Mlym description: The Malayalam alphabet. Used in the southern Indian state of Kerala. - type: string enum: - Mong description: The Mongolian alphabet. - type: string enum: - Mymr description: The Myanmar (Burmese) alphabet. - type: string enum: - Orya description: The Oriya (Odia) alphabet. Used in the eastern Indian state of Odisha. - type: string enum: - Sinh description: The Sinhala alphabet. - type: string enum: - Sund description: The Sundanese alphabet. - type: string enum: - Syrc description: The Syriac alphabet. - type: string enum: - Taml description: The Tamil alphabet. Used in the southern Indian state of Tamilnadu. - type: string enum: - Telu description: The Telugu language alphabet. Used in the southern Indian state of Andhra pradesh. - type: string enum: - Thaa description: The Thaana (Maldivian) alphabet. - type: string enum: - Thai description: The Thai alphabet. Used in Thailand. - type: string enum: - Tibt description: The Tibetan alphabet. - type: string enum: - Yiii description: The Yi alphabet. - type: string enum: - Zyyy description: The orthography cannot be determined. - type: string enum: - Zzzz description: The orthography is unknown. business_name: title: Business Name description: The business name of the party. type: object properties: business_name: description: Required. The business name of the party. type: string minLength: 0 maxLength: 300 pattern: ^.*$ orthography: $ref: "#/components/schemas/orthography" person_name: title: Name description: The name of a person. type: object properties: prefix: description: The prefix, or title, to the party's name. type: string minLength: 0 maxLength: 140 pattern: ^.*$ given_name: description: When the party is a person, the party's given, or first, name. type: string minLength: 0 maxLength: 140 pattern: ^.*$ surname: description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname. type: string minLength: 0 maxLength: 140 pattern: ^.*$ middle_name: description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. type: string minLength: 0 maxLength: 140 pattern: ^.*$ suffix: description: The suffix for the party's name. type: string minLength: 0 maxLength: 140 pattern: ^.*$ full_name: description: When the party is a person, the party's full name. type: string minLength: 0 maxLength: 300 pattern: ^.*$ orthography: $ref: "#/components/schemas/orthography" country_code: description: The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
type: string minLength: 2 maxLength: 2 pattern: ^([A-Z]{2}|C2)$ address_portable: title: Portable Postal Address (Medium-Grained) description: "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinp\ ut/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form\ -controls-the-autocomplete-attribute)." type: object required: - country_code properties: address_line_1: description: The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. type: string minLength: 0 maxLength: 300 pattern: ^.*$ address_line_2: description: The second line of the address, for example, a suite or apartment number. type: string minLength: 0 maxLength: 300 pattern: ^.*$ address_line_3: description: The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address. type: string minLength: 0 maxLength: 100 pattern: ^.*$ admin_area_4: description: The neighborhood, ward, or district. This is smaller than `admin_area_level_3` or `sub_locality`. Value is: type: string minLength: 0 maxLength: 100 pattern: ^.*$ admin_area_3: description: The sub-locality, suburb, neighborhood, or district. This is smaller than `admin_area_level_2`. Value is: type: string minLength: 0 maxLength: 100 pattern: ^.*$ admin_area_2: description: A city, town, or village. Smaller than `admin_area_level_1`. type: string minLength: 0 maxLength: 120 pattern: ^.*$ admin_area_1: description: The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: type: string minLength: 0 maxLength: 300 pattern: ^.*$ postal_code: description: The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). type: string minLength: 0 maxLength: 60 pattern: ^.*$ country_code: $ref: "#/components/schemas/country_code" address_details: title: Address Details description: The non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`. type: object properties: street_number: description: The street number. type: string minLength: 0 maxLength: 100 pattern: ^.*$ street_name: description: The street name. Just `Drury` in `Drury Lane`. type: string minLength: 0 maxLength: 100 pattern: ^.*$ street_type: description: The street type. For example, avenue, boulevard, road, or expressway. type: string minLength: 0 maxLength: 100 pattern: ^.*$ delivery_service: description: The delivery service. Post office box, bag number, or post office name. type: string minLength: 0 maxLength: 100 pattern: ^.*$ building_name: description: A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House. type: string minLength: 0 maxLength: 100 pattern: ^.*$ sub_building: description: The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment. type: string minLength: 0 maxLength: 100 pattern: ^.*$ contact_name_address: title: contact_information description: The contact information of the user. Includes name and address. type: object allOf: - $ref: "#/components/schemas/business_name" - type: object properties: name: allOf: - $ref: "#/components/schemas/person_name" - description: The first and Last name of the recipient. address: allOf: - $ref: "#/components/schemas/address_portable" - description: The address of the recipient. restrictive_email_address: description: The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
type: string minLength: 3 maxLength: 254 pattern: ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(?!\.)){1,64}(?Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists. type: string minLength: 3 maxLength: 254 pattern: ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$ tax: title: tax description: The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total. type: object required: - name - percent properties: name: description: The name of the tax applied on the invoice items. type: string minLength: 0 maxLength: 100 pattern: ^[\s\S]*$ percent: allOf: - $ref: "#/components/schemas/percentage" - description: The tax rate. Value is from `0` to `100`. Supports up to five decimal places. amount: allOf: - $ref: "#/components/schemas/money" - description: The calculated tax amount. The tax amount is added to the item total. readOnly: true tax_note: description: The tax note used to track the tax related data. type: string minLength: 0 maxLength: 40 pattern: ^[\s\S]*$ discount: title: discount description: The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total. type: object properties: percent: allOf: - $ref: "#/components/schemas/percentage" - description: The discount as a percentage value. Value is from `0` to `100`. Supports up to five decimal places. amount: allOf: - $ref: "#/components/schemas/money" - description: The invoice level discount amount. Value is from `0` to `1000000`. Supports up to two decimal places. unit_of_measure: title: unit_of_measure description: The unit of measure for the invoiced item. type: string enum: - QUANTITY - HOURS - AMOUNT oneOf: - type: string enum: - QUANTITY description: The unit of measure is quantity. This invoice template is typically used for physical goods. - type: string enum: - HOURS description: The unit of measure is hours. This invoice template is typically used for services. - type: string enum: - AMOUNT description: The unit of measure is amount. This invoice template is typically used when only amount is required. item: title: item description: An array of invoice line item information. The maximum items for an invoice is `100`. type: object required: - name - quantity - unit_amount properties: id: description: The ID of the invoice line item. type: string minLength: 0 maxLength: 22 pattern: ^[\S\s]*$ readOnly: true name: description: The item name for the invoice line item. type: string minLength: 0 maxLength: 200 pattern: ^[\S\s]*$ description: description: The item description for the invoice line item. type: string minLength: 0 maxLength: 1000 pattern: ^[\S\s]*$ quantity: description: The quantity of the item that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places. type: string minLength: 0 maxLength: 14 pattern: ^\d+(.\d{1,5})?$ unit_amount: allOf: - $ref: "#/components/schemas/money" - description: The unit price of the item. This does not include tax and discount. Value is from `-1000000` to `1000000`. Supports up to two decimal places. tax: allOf: - $ref: "#/components/schemas/tax" - description: The tax associated with the item. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places. item_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The date when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. discount: $ref: "#/components/schemas/discount" unit_of_measure: allOf: - $ref: "#/components/schemas/unit_of_measure" - description: The unit of measure for the invoiced item. For `AMOUNT` the `unit_amount` and `quantity` are not shown on the invoice.
Note: If your specify different `unit_of_measure` values for the same invoice, the invoice uses the first value.
partial_payment: title: partial_payment description: The partial payment details. Includes the minimum amount that the invoicer expects from the payer. type: object properties: allow_partial_payment: description: Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments.
Note: This feature is not available for users in `India`, `Brazil`, or `Israel`.
type: boolean default: false minimum_amount_due: allOf: - $ref: "#/components/schemas/money" - description: The minimum amount allowed for a partial payment. Valid only when `allow_partial_payment` is `true`. base_configuration: title: base_configuration description: The base configuration details. Includes tax information, tip, and partial payment. type: object properties: tax_calculated_after_discount: description: Indicates whether the tax is calculated before or after a discount. If `false`, the tax is calculated before a discount. If `true`, the tax is calculated after a discount. type: boolean default: true tax_inclusive: description: Indicates whether the unit price includes tax. type: boolean default: false allow_tip: description: Indicates whether the invoice enables the customer to enter a tip amount during payment. If `true`, the invoice shows a tip amount field so that the customer can enter a tip amount. If `false`, the invoice does not show a tip amount field.
Note: This feature is not available for users in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
type: boolean default: false partial_payment: $ref: "#/components/schemas/partial_payment" discount_mode_preference: description: Represents the user's preferred mode for creating discounts. Determines whether "One-time discount" or "Save for future invoices" is preselected when creating a new discount. type: string enum: - ONE_TIME - SAVE_FOR_FUTURE oneOf: - type: string enum: - ONE_TIME description: Indicates that the user prefers creating one-time discounts by default. - type: string enum: - SAVE_FOR_FUTURE description: Indicates that the user prefers saving discounts for future invoices by default. configurable_theme: title: Theme configuration description: The theme configuration that defines the visual appearance of the invoice buyer experience and email. Pass an empty object to use the default theme. type: object properties: primary_color: description: "The primary color chosen by the merchant for branding the invoice buyer experience and email. Accepts a hex color code in #RGB or #RRGGBB format." type: string minLength: 4 maxLength: 7 pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$ template_configuration: title: template_configuration description: The template configuration details. Includes tax information, tip, and partial payment. type: object allOf: - $ref: "#/components/schemas/base_configuration" - type: object properties: has_conditional_rule: description: Indicates whether conditional pricing rules are applied to the invoice. If `true`, pricing rules (such as discounts or surcharges based on specific conditions) are applied. If `false`, no conditional pricing rules are applied. type: boolean default: false save_item_for_future: description: Indicates whether the item should be saved for future invoices. type: boolean default: true show_additional_item_fields: description: Indicates whether items tray should be shown for invoices or not. If `true`, additional fields containing items tray will be shown. If `false`, the items tray will be hidden. type: boolean default: false discount_mode_preference: $ref: "#/components/schemas/discount_mode_preference" theme: allOf: - $ref: "#/components/schemas/configurable_theme" - description: The theme configuration for the template. Defines the visual appearance of the invoice buyer experience and email when invoice is created using the template in UI.
Note: Setting a theme on a template does not automatically carry over to invoices created using this template. To apply a theme to an invoice, set it directly on the invoice configuration.
override_payment_method_type: title: override_payment_method_type description: The payment method types that can be configured in the payment method overrides object for invoice payments.
Note: To use PAY_BY_BANK, you must first complete the onboarding process. Visit the onboarding page to get started. Once onboarding is complete, you can configure PAY_BY_BANK as a payment method.
type: string enum: - PAY_BY_BANK - ACH oneOf: - type: string enum: - PAY_BY_BANK description: Enables the buyer to pay the invoice directly from their bank account. Available only for US-based merchants and invoices with USD currency. - type: string enum: - ACH description: Enables the buyer to pay the invoice via ACH bank transfer. override_payment_method_rule_type: title: override_payment_method_rule_type description: The type of rule that can be applied to a payment method configured via payment method overrides object on an invoice. Each rule controls how a payment method behaves based on the invoice total.
System-defined threshold limits by payment method:
  1. PAY_BY_BANK - $1000
type: string enum: - EXCLUSIVE_ABOVE_AMOUNT_THRESHOLD - ALLOW_ONLY_ACH oneOf: - type: string enum: - EXCLUSIVE_ABOVE_AMOUNT_THRESHOLD description: When the invoice total exceeds the system-defined threshold, this rule restricts the invoice to accept only the specified payment method and disables all other payment methods. This rule is currently compatible only with the PAY_BY_BANK payment method. - type: string enum: - ALLOW_ONLY_ACH description: Restricts the invoice to accept payment only via ACH bank transfer and disables all other payment methods. override_payment_method_rule: title: override_payment_method_rule description: The details about a payment method override rule applied to the invoice via payment method overrides object. type: object required: - rule_type - rule_value properties: rule_type: $ref: "#/components/schemas/override_payment_method_rule_type" rule_value: description: The value associated with the payment method override rule. For the `EXCLUSIVE_ABOVE_AMOUNT_THRESHOLD` rule type, set this to `true` to enable the rule or `false` to disable it. type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9\s,.]+$ override_payment_method_detail: title: override_payment_method_detail description: The details about a payment method override configured for the invoice via payment method overrides object. type: object properties: payment_method_type: $ref: "#/components/schemas/override_payment_method_type" enabled: description: Indicates whether the specified payment method is enabled for the invoice. When set to `true`, the payment method is available for the buyer to use. When set to `false`, the payment method is disabled. type: boolean rules: description: The list of payment method override rules applied to the invoice via payment method overrides object. Each rule defines a specific restriction or behavior for the payment method, such as making it the exclusive payment option when the invoice total exceeds a system-defined threshold. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/override_payment_method_rule" configuration: title: configuration description: The invoice configuration details. Includes partial payment, tip, and tax calculated after discount. type: object allOf: - $ref: "#/components/schemas/template_configuration" - type: object properties: template_id: description: The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.
Note: This is an optional field. If you wish to customize the invoice layout using a specific template, provide a valid template ID here. You can either use an existing template ID or create a new template via the create template API and then use the newly created template's ID.
type: string minLength: 0 maxLength: 30 pattern: ^[\S\s]*$ default: PayPal system template payment_method_overrides: description: "The payment method override configurations for the invoice. Defines which payment methods are enabled and any rules that control payment behavior. When provided during invoice creation or update, this array replaces any existing payment method override configuration for the invoice.
Note: Payment method availability depends on the merchant's country, the buyer's country, and the invoice amount. Override configurations only take effect if the specified payment method is available for the invoice.
" type: array minItems: 1 maxItems: 15 items: $ref: "#/components/schemas/override_payment_method_detail" theme: $ref: "#/components/schemas/configurable_theme" aggregated_discount: title: aggregated_discount description: The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent. type: object properties: invoice_discount: $ref: "#/components/schemas/discount" item_discount: allOf: - $ref: "#/components/schemas/money" - description: The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount. shipping_cost: title: shipping_cost description: The shipping fee for all items. Includes tax on shipping. type: object properties: amount: allOf: - $ref: "#/components/schemas/money" - description: The shipping amount. Value is from `0` to `1000000`. Supports up to two decimal places. tax: allOf: - $ref: "#/components/schemas/tax" - description: The tax associated with the shipping. custom_amount: title: custom_amount description: The custom amount to apply to an invoice. If you include a label, you must include a custom amount. type: object required: - label properties: label: description: The label to the custom amount of the invoice. type: string minLength: 0 maxLength: 50 pattern: ^[\S\s]*$ amount: allOf: - $ref: "#/components/schemas/money" - description: The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places. amount_with_breakdown: title: amount_with_breakdown description: The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any. type: object properties: item_total: allOf: - $ref: "#/components/schemas/money" - description: The subtotal for all items. Must equal the sum of (`items[].unit_amount` * `items[].quantity`) for all items. discount: $ref: "#/components/schemas/aggregated_discount" tax_total: allOf: - $ref: "#/components/schemas/money" - description: The aggregated amount of the item and shipping taxes. shipping: $ref: "#/components/schemas/shipping_cost" custom: $ref: "#/components/schemas/custom_amount" amount_summary_detail: title: amount_summary_detail description: The invoice amount summary of item total, discount, tax total, and shipping. type: object properties: currency_code: $ref: "#/components/schemas/currency_code" value: description: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). type: string minLength: 0 maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ breakdown: $ref: "#/components/schemas/amount_with_breakdown" invoice_item_field: title: invoice_item_field description: The field name for the invoice item. type: string enum: - ITEM_DESCRIPTION - ITEM_DATE - ITEM_TAX - ITEM_DISCOUNT oneOf: - type: string enum: - ITEM_DESCRIPTION description: The description of the item. - type: string enum: - ITEM_DATE description: The date of the item. - type: string enum: - ITEM_TAX description: The tax of the item. - type: string enum: - ITEM_DISCOUNT description: The discount of the item. display_preference: title: display_preference description: The display preference of the field. type: object properties: hidden: description: Indicates whether to show or hide the field. type: boolean invoice_item_setting: title: invoice_item_setting description: The invoice item setting. type: object properties: field_name: $ref: "#/components/schemas/invoice_item_field" display_preference: $ref: "#/components/schemas/display_preference" invoice_additional_settings_field: title: invoice_additional_settings_field description: The field names for additional sections in the invoice. type: string enum: - ATTACHMENT - MEMO - REFERENCE oneOf: - type: string enum: - ATTACHMENT description: The file attachments added to the invoice. - type: string enum: - MEMO description: The internal memo in the invoice that is visible only to the invoicer. - type: string enum: - REFERENCE description: The reference number in the invoice for tracking or correlation. invoice_additional_setting: title: invoice_additional_setting description: The invoice additional setting. type: object properties: field_name: $ref: "#/components/schemas/invoice_additional_settings_field" display_preference: $ref: "#/components/schemas/display_preference" invoice_policy_and_agreement_settings_field: title: invoice_policy_and_agreement_settings_field description: The field names for the policy and agreement details in the invoice. type: string enum: - CANCELLATION_POLICY - PAYMENT_TERMS - RETURN_POLICY - SERVICE_AGREEMENT - TERMS_AND_CONDITIONS oneOf: - type: string enum: - CANCELLATION_POLICY description: Cancellation policy information in the invoice. - type: string enum: - PAYMENT_TERMS description: Payment terms information in the invoice. - type: string enum: - RETURN_POLICY description: Return policy information in the invoice. - type: string enum: - SERVICE_AGREEMENT description: Service agreement information in the invoice. - type: string enum: - TERMS_AND_CONDITIONS description: Terms and conditions information in the invoice. invoice_policy_and_agreement_setting: title: invoice_policy_and_agreement_setting description: The invoice policy and agreement setting. type: object properties: field_name: $ref: "#/components/schemas/invoice_policy_and_agreement_settings_field" display_preference: $ref: "#/components/schemas/display_preference" invoice_details_settings_field: title: invoice_details_settings_field description: The field names for the invoice details. type: string enum: - ORDER_DETAILS - PROJECT_DETAILS - SERVICE_DETAILS oneOf: - type: string enum: - ORDER_DETAILS description: Order details information in the invoice. - type: string enum: - PROJECT_DETAILS description: Project details information in the invoice. - type: string enum: - SERVICE_DETAILS description: Service details information in the invoice. invoice_details_setting: title: invoice_details_setting description: The invoice details setting. type: object properties: field_name: $ref: "#/components/schemas/invoice_details_settings_field" display_preference: $ref: "#/components/schemas/display_preference" invoice_settings: title: invoice_settings description: The settings for the invoice. type: object properties: invoice_item_settings: description: The settings for the invoice items. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/invoice_item_setting" invoice_additional_settings: description: The settings for the invoice additional fields. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/invoice_additional_setting" invoice_policy_and_agreement_settings: description: The settings for the invoice policy and agreement fields. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/invoice_policy_and_agreement_setting" invoice_details_settings: description: The settings for the invoice details fields. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/invoice_details_setting" payment_type: title: payment_type description: The payment type. Can be PayPal or an external payment. Includes cash or a check. type: string enum: - PAYPAL - EXTERNAL oneOf: - type: string enum: - PAYPAL description: The payment type is PayPal. - type: string enum: - EXTERNAL description: The payment type is an external cash or a check payment. payment_method: title: payment_method description: The payment mode or method through which the invoicer can accept the payments. type: string enum: - BANK_TRANSFER - CASH - CHECK - CREDIT_CARD - DEBIT_CARD - PAYPAL - WIRE_TRANSFER - OTHER oneOf: - type: string enum: - BANK_TRANSFER description: Payments can be received through bank transfers. - type: string enum: - CASH description: Payments can be received as cash. - type: string enum: - CHECK description: Payments can be received as check. - type: string enum: - CREDIT_CARD description: Payments can be received through credit card payments. - type: string enum: - DEBIT_CARD description: Payments can be received through debit card payments. - type: string enum: - PAYPAL description: Payments can be received through paypal payments. - type: string enum: - WIRE_TRANSFER description: Payments can be received through wire transfer. - type: string enum: - OTHER description: Payments can be received through other modes. payment_detail: title: payment_detail description: The payment details of the invoice. Includes payment type, method, date, discount, and transaction type. type: object required: - method properties: type: allOf: - $ref: "#/components/schemas/payment_type" - description: The payment type in an invoicing flow which can be PayPal or an external cash or check payment. readOnly: true payment_id: description: The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type. type: string minLength: 0 maxLength: 22 pattern: ^[\S\s]*$ payment_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The date when the invoice was paid, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*. payment_date_time: allOf: - $ref: "#/components/schemas/date_time" - description: "The date-time when the invoice was paid. For example, *yyyy*-*MM*-*dd* *T* *HH*: *mm*: *ss* *z*. The time zone will be UTC." method: $ref: "#/components/schemas/payment_method" note: description: A note associated with an external cash or check payment. type: string minLength: 0 maxLength: 2000 pattern: ^[\S\s]*$ amount: allOf: - $ref: "#/components/schemas/money" - description: The payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due. shipping_info: allOf: - $ref: "#/components/schemas/contact_name_address" - description: The recipient's shipping information. Includes the user's contact information, which includes name and address. payments: title: payments description: An array of payments registered against the invoice. type: object properties: paid_amount: allOf: - $ref: "#/components/schemas/money" - description: The aggregated payment amounts against this invoice. readOnly: true transactions: description: An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type. type: array minItems: 0 maxItems: 100 readOnly: true items: $ref: "#/components/schemas/payment_detail" refund_detail: title: refund_detail description: The refund details of the invoice. Includes the refund type, date, amount, and method. type: object required: - method properties: type: allOf: - $ref: "#/components/schemas/payment_type" - description: The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the `EXTERNAL` refund type. The `PAYPAL` refund type is supported for backward compatibility. readOnly: true refund_id: description: The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type. type: string minLength: 0 maxLength: 22 pattern: ^[\S\s]*$ readOnly: true refund_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The date when the invoice was refunded, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2014-02-27`. amount: allOf: - $ref: "#/components/schemas/money" - description: The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded. method: $ref: "#/components/schemas/payment_method" refunds: title: refunds description: The invoicing refund details. Includes the refund type, date, amount, and method. type: object properties: refund_amount: allOf: - $ref: "#/components/schemas/money" - description: The aggregated refund amounts. readOnly: true transactions: description: An array of refund details for the invoice. Includes the refund type, date, amount, and method. type: array minItems: 0 maxItems: 100 readOnly: true items: $ref: "#/components/schemas/refund_detail" invoice: title: invoice description: The invoice details which includes all information of the invoice like items, billing information. type: object required: - detail properties: id: description: The ID of the invoice. type: string minLength: 0 maxLength: 30 pattern: ^[\s\S]*$ readOnly: true parent_id: description: The parent ID to an invoice that defines the group invoice to which the invoice is related. type: string minLength: 0 maxLength: 30 pattern: ^[\s\S]*$ readOnly: true status: allOf: - $ref: "#/components/schemas/invoice_status" - readOnly: true detail: $ref: "#/components/schemas/invoice_detail" invoicer: allOf: - $ref: "#/components/schemas/invoicer_info" - description: The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL. primary_recipients: description: The billing and shipping information. Includes name, email, address, phone and language. type: array minItems: 0 maxItems: 100 items: allOf: - $ref: "#/components/schemas/recipient_info" - title: primary_recipient additional_recipients: description: "An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
" type: array minItems: 0 maxItems: 100 items: allOf: - $ref: "#/components/schemas/email_address" - title: additional_recipient items: description: An array of invoice line item information. type: array minItems: 0 maxItems: 100 items: $ref: "#/components/schemas/item" configuration: $ref: "#/components/schemas/configuration" amount: $ref: "#/components/schemas/amount_summary_detail" settings: $ref: "#/components/schemas/invoice_settings" due_amount: allOf: - $ref: "#/components/schemas/money" - description: The due amount, which is the balance amount outstanding after payments. readOnly: true gratuity: allOf: - $ref: "#/components/schemas/money" - description: The amount paid by the payer as gratuity to the invoicer. readOnly: true payments: $ref: "#/components/schemas/payments" effective_invoice_total: allOf: - $ref: "#/components/schemas/money" - description: The effective total amount of the invoice after applying conditional rules. The conditional rules include early payment discount, late payment surcharge, and auto cancellation details. effective_due_amount: allOf: - $ref: "#/components/schemas/money" - description: The effective due amount of the invoice after applying conditional rules. The conditional rules include early payment discount, late payment surcharge, and auto cancellation details. refunds: $ref: "#/components/schemas/refunds" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: $ref: "#/components/schemas/link_description" invoices: title: invoices description: An array of merchant invoices. Includes the total invoices count and [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links) for navigation. type: object properties: total_pages: description: The total number of pages that are available for the search criteria.
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next
type: integer minimum: 0 maximum: 2147483647 readOnly: true total_items: description: The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of total_items is constant. The value MAY change from one request to the next.
type: integer minimum: 0 maximum: 2147483647 readOnly: true items: description: The list of invoices that match the search criteria. type: array minItems: 0 maxItems: 100 readOnly: true items: $ref: "#/components/schemas/invoice" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: $ref: "#/components/schemas/link_description" notification: title: notification description: The email or SMS notification to send to the invoicer or payer on sending an invoice. type: object properties: subject: description: The subject of the email that is sent as a notification to the recipient.
Note: User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.
type: string minLength: 0 maxLength: 4000 pattern: ^[\S\s]*$ note: description: A note to the payer.
Note: User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.
type: string minLength: 0 maxLength: 4000 pattern: ^[\S\s]*$ send_to_invoicer: description: Indicates whether to send a copy of the email to the merchant. type: boolean default: false send_to_recipient: description: Indicates whether to send a copy of the email to the recipient. type: boolean default: true additional_recipients: description: "An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
" type: array minItems: 0 maxItems: 100 items: allOf: - $ref: "#/components/schemas/email_address" - title: additional_recipient payment_reference: title: payment_reference description: The reference to the payment detail. type: object properties: payment_id: description: The ID for the invoice payment. type: string minLength: 1 maxLength: 22 pattern: ^[0-9A-Za-z_-]+$ readOnly: true refund_reference: title: refund_reference description: The reference to the refund payment detail. type: object properties: refund_id: description: The ID of the refund of an invoice payment. type: string minLength: 1 maxLength: 22 pattern: ^[0-9A-Za-z_-]+$ readOnly: true qr_config: title: qr_config description: The configuration for a QR code. type: object properties: width: description: The width, in pixels, of the QR code image. Value is from `150` to `500`. type: integer minimum: 150 maximum: 500 default: 500 height: description: The height, in pixels, of the QR code image. Value is from `150` to `500`. type: integer minimum: 150 maximum: 500 default: 500 action: description: The type of URL for which to generate a QR code. Valid values are `pay` and `details`. type: string minLength: 0 maxLength: 7 pattern: ^([Pp][Aa][Yy]|[Dd][Ee][Tt][Aa][Ii][Ll][Ss])$ default: pay fetchtype: title: fetchtype description: Is the fetch type invoice number or id. type: object properties: fetch_id: description: Decides whether to use the number or the ID. type: boolean default: "false" invoice_number: title: Invoice Number description: The invoice number. type: object properties: invoice_number: description: The invoice number. If you omit this value, an auto-incremented number from the last number is used. type: string minLength: 1 maxLength: 25 pattern: ^[\S\s]*$ readOnly: true invoice_id: description: Resource Id. type: string minLength: 1 maxLength: 24 pattern: ^(INV2-)[A-Z0-9\-]{19}$ readOnly: true amount_range: title: amount_range description: The amount range. type: object required: - lower_amount - upper_amount properties: lower_amount: allOf: - $ref: "#/components/schemas/money" - description: The lower limit of the amount range. upper_amount: allOf: - $ref: "#/components/schemas/money" - description: The upper limit of the amount range. date_range: title: date_range description: The date range. Filters invoices by creation date, invoice date, due date, and payment date. type: object required: - end - start properties: start: allOf: - $ref: "#/components/schemas/date_no_time" - description: The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date. end: allOf: - $ref: "#/components/schemas/date_no_time" - description: The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date. date_time_range: title: Date and Time Range description: The date and time range. Filters invoices by creation date, invoice date, due date, and payment date. type: object required: - end - start properties: start: allOf: - $ref: "#/components/schemas/date_time" - description: The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date. end: allOf: - $ref: "#/components/schemas/date_time" - description: "The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date.
Note: The regular expression provides guidance but does not reject all invalid dates.

Minimum length: 20.
Maximum length: 64
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]\ ([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]\ |[+-][0-9]{2}:[0-9]{2})$" search_data: title: search_data description: The invoice search parameters. type: object properties: recipient_email: description: Filters the search by the email address. type: string minLength: 0 maxLength: 254 pattern: ^[\S\s]*$ recipient_first_name: description: Filters the search by the recipient first name. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ recipient_last_name: description: Filters the search by the recipient last name. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ recipient_business_name: description: Filters the search by the recipient business name. type: string minLength: 0 maxLength: 300 pattern: ^[\S\s]*$ invoice_number: description: Filters the search by the invoice number. type: string minLength: 0 maxLength: 25 pattern: ^[\S\s]*$ status: description: An array of status values. type: array minItems: 0 maxItems: 5 items: $ref: "#/components/schemas/invoice_status" reference: description: The reference data. Includes a Purchase Order (PO) number. type: string minLength: 0 maxLength: 120 pattern: ^[\S\s]*$ currency_code: $ref: "#/components/schemas/currency_code" memo: description: A private bookkeeping memo for the user. type: string minLength: 0 maxLength: 500 pattern: ^[\S\s]*$ total_amount_range: allOf: - $ref: "#/components/schemas/amount_range" - description: Filters the search by the total amount. invoice_date_range: allOf: - $ref: "#/components/schemas/date_range" - description: Filters the search by a date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). due_date_range: allOf: - $ref: "#/components/schemas/date_range" - description: Filters the search by a due date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). payment_date_range: $ref: "#/components/schemas/date_time_range" creation_date_range: allOf: - $ref: "#/components/schemas/date_time_range" - description: Filters the search by a creation date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). archived: description: Indicates whether to list merchant-archived invoices in the response. Value is: type: boolean fields: description: A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are items, payments, refunds, additional_recipients_info, and attachments. type: array minItems: 0 maxItems: 5 items: title: field description: The name of the field. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ template_detail: title: template_detail description: The template-related details. Includes notes, terms and conditions, memo, and attachments. type: object allOf: - $ref: "#/components/schemas/additional_detail" - type: object properties: payment_term: allOf: - $ref: "#/components/schemas/payment_term" - description: The payment due date for the invoice. Value is either but not both term_type or due_date. metadata: $ref: "#/components/schemas/template_metadata" template_info: title: template_info description: The template details. Includes invoicer business information, invoice recipients, items, and configuration. type: object properties: detail: $ref: "#/components/schemas/template_detail" invoicer: allOf: - $ref: "#/components/schemas/invoicer_info" - description: The invoicer information. Includes business name, email, address, phone, fax, tax ID, additional notes, and logo URL. primary_recipients: description: The billing and shipping information. Includes name, email, address, phone, and language. type: array minItems: 0 maxItems: 100 items: $ref: "#/components/schemas/recipient_info" additional_recipients: description: "An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
" type: array minItems: 0 maxItems: 100 items: allOf: - $ref: "#/components/schemas/email_address" - title: additional_recipient items: description: An array of invoice line-item information. type: array minItems: 0 maxItems: 100 items: $ref: "#/components/schemas/item" configuration: $ref: "#/components/schemas/template_configuration" amount: $ref: "#/components/schemas/amount_summary_detail" due_amount: allOf: - $ref: "#/components/schemas/money" - description: The amount due for the invoice. readOnly: true template_item_field: title: template_item_field description: The field names for the invoice line items in the template. type: string enum: - ITEMS_QUANTITY - ITEMS_DESCRIPTION - ITEMS_DATE - ITEMS_DISCOUNT - ITEMS_TAX oneOf: - type: string enum: - ITEMS_QUANTITY description: The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places. - type: string enum: - ITEMS_DESCRIPTION description: The description of the item in the invoice template. - type: string enum: - ITEMS_DATE description: The date in invoice template when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. - type: string enum: - ITEMS_DISCOUNT description: The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total. - type: string enum: - ITEMS_TAX description: The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places. template_display_preference: title: template_display_preference description: The template display preference. type: object properties: hidden: description: Indicates whether to show or hide this field. type: boolean default: false template_item_setting: title: template_item_setting description: The template item setting. Sets a template as the default template or edit template. type: object properties: field_name: allOf: - $ref: "#/components/schemas/template_item_field" - description: The field name in `template_data` for which to map corresponding display preferences. display_preference: $ref: "#/components/schemas/template_display_preference" template_subtotal_field: title: template_subtotal_field description: The field names in the template for discount, shipping, and custom amounts. type: string enum: - DISCOUNT - SHIPPING - CUSTOM - SHIPPING_TAX oneOf: - type: string enum: - DISCOUNT description: The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total. - type: string enum: - SHIPPING description: The shipping fee for all items in the invoice template. Also includes the tax on shipping. - type: string enum: - CUSTOM description: The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount. - type: string enum: - SHIPPING_TAX description: The tax on shipping fee for all items in the invoice template. template_subtotal_setting: title: template_subtotal_setting description: The template subtotal setting. Includes the field name and display preference. type: object properties: field_name: allOf: - $ref: "#/components/schemas/template_subtotal_field" - description: The field name in `template_data` for which to map corresponding display preferences. display_preference: $ref: "#/components/schemas/template_display_preference" template_details_settings_field: title: template_details_settings_field description: The field names for the invoice details in the template. type: string enum: - ORDER_DETAILS - PROJECT_DETAILS - SERVICE_DETAILS oneOf: - type: string enum: - ORDER_DETAILS description: Order details information in the invoice template. - type: string enum: - PROJECT_DETAILS description: Project details information in the invoice template. - type: string enum: - SERVICE_DETAILS description: Service details information in the invoice template. template_setting_display_preference: title: template_setting_display_preference description: The template setting display preference. type: object properties: hidden: description: Indicates whether to show or hide this field. type: boolean template_details_setting: title: template_details_setting description: The template invoice details setting. Includes the field name and display preference for order, project, and service details. type: object properties: field_name: allOf: - $ref: "#/components/schemas/template_details_settings_field" - description: The field name for which to map corresponding display preferences. display_preference: $ref: "#/components/schemas/template_setting_display_preference" template_policy_and_agreement_settings_field: title: template_policy_and_agreement_settings_field description: The field names for the policy and agreement details in the template. type: string enum: - CANCELLATION_POLICY - PAYMENT_TERMS - RETURN_POLICY - SERVICE_AGREEMENT - TERMS_AND_CONDITIONS oneOf: - type: string enum: - CANCELLATION_POLICY description: Cancellation policy information in the invoice template. - type: string enum: - PAYMENT_TERMS description: Payment terms information in the invoice template. - type: string enum: - RETURN_POLICY description: Return policy information in the invoice template. - type: string enum: - SERVICE_AGREEMENT description: Service agreement information in the invoice template. - type: string enum: - TERMS_AND_CONDITIONS description: Terms and conditions information in the invoice template. template_policy_and_agreement_setting: title: template_policy_and_agreement_setting description: The template policy and agreement setting. Includes the field name and display preference for policy and agreement related fields. type: object properties: field_name: allOf: - $ref: "#/components/schemas/template_policy_and_agreement_settings_field" - description: The field name for which to map corresponding display preferences. display_preference: $ref: "#/components/schemas/template_setting_display_preference" template_additional_settings_field: title: template_additional_settings_field description: The field names in the invoice template for additional sections, such as reference, attachments, or memo. type: string enum: - ATTACHMENT - MEMO - REFERENCE oneOf: - type: string enum: - ATTACHMENT description: The file attachments added to the invoice template. - type: string enum: - MEMO description: The internal memo in the invoice template that is visible only to the invoicer. - type: string enum: - REFERENCE description: The reference number in the invoice template for tracking or correlation. template_additional_setting: title: template_additional_setting description: The template additional setting. Includes the field name and display preference. type: object properties: field_name: allOf: - $ref: "#/components/schemas/template_additional_settings_field" - description: Indicates which field or section of the invoice template this display preference applies to, as defined in `template_additional_settings_field.json`. display_preference: $ref: "#/components/schemas/template_setting_display_preference" template_settings: title: template_settings description: The template settings. Sets a template as the default template or edit template. type: object properties: template_item_settings: description: The template item headers display preference. type: array minItems: 0 maxItems: 32767 items: $ref: "#/components/schemas/template_item_setting" template_subtotal_settings: description: The template subtotal headers display preference. type: array minItems: 0 maxItems: 32767 items: $ref: "#/components/schemas/template_subtotal_setting" template_details_settings: description: The template invoice details settings for order, project, and service details. type: array minItems: 0 maxItems: 32767 items: $ref: "#/components/schemas/template_details_setting" template_policy_and_agreement_settings: description: The template policy and agreement settings for terms, cancellation, and return policies. type: array minItems: 0 maxItems: 32767 items: $ref: "#/components/schemas/template_policy_and_agreement_setting" template_additional_settings: description: The template additional fields that define display preferences for references, attachments, and memos. type: array minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/template_additional_setting" template: title: template description: The template with invoice details to load with all captured fields. type: object properties: id: description: The ID of the template. type: string minLength: 0 maxLength: 30 pattern: ^[\S\s]*$ readOnly: true name: description: The template name.
Note: The template name must be unique.
type: string minLength: 1 maxLength: 500 pattern: ^[\S\s]*$ description: description: The detailed description of the template. type: string minLength: 1 maxLength: 160 pattern: ^[\S\s]*$ default_template: description: Indicates whether this template is the default template. A invoicer can have one default template. type: boolean template_info: $ref: "#/components/schemas/template_info" settings: allOf: - $ref: "#/components/schemas/template_settings" - description: The template settings. Describes which fields to show or hide when you create an invoice. unit_of_measure: allOf: - $ref: "#/components/schemas/unit_of_measure" - description: The unit of measure for the template. Value is quantity, hours, or amount. standard_template: description: Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates. type: boolean readOnly: true links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" - readOnly: true templates: title: templates description: An array of merchant-created templates with associated details that include the emails, addresses, and phone numbers from the user's PayPal profile. type: object properties: addresses: description: An array of addresses in the user's PayPal profile. type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: "#/components/schemas/address_portable" - title: address emails: allOf: - $ref: "#/components/schemas/email_address" - description: An array of emails in the user's PayPal profile. readOnly: true phones: description: An array of phone numbers in the user's PayPal profile. type: array minItems: 0 maxItems: 32767 items: allOf: - $ref: "#/components/schemas/phone_detail" - title: phone templates: description: An array of details for each template. If `fields` is `none`, returns only the template name, ID, and default status. type: array minItems: 0 maxItems: 32767 items: $ref: "#/components/schemas/template" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" - readOnly: true conditional_rule_time_based_uuid: description: A unique identifier for the conditional rule, This ID is generated as a time-based UUID (version 1) to ensure uniqueness and traceability of the rule creation time. type: string minLength: 39 maxLength: 39 pattern: ^CR-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{12}$ conditional_rule_type: title: conditional_rule_type description: This enum defines what type of rule is applying for the particular invoice. type: string enum: - EARLY_PAYMENT_DISCOUNT - AUTO_CANCEL oneOf: - type: string enum: - EARLY_PAYMENT_DISCOUNT description: A discount applied if the invoice is paid before a specified date or within a certain period after the issue date. - type: string enum: - AUTO_CANCEL description: A rule to automatically cancel the invoice if it is not paid by a specified date or a certain period after the due date. conditional_rule_value_type: title: conditional_rule_value_type description: Type of the stored discount. Used to determine whether its percentage or absolute currency value. type: string enum: - PERCENT - AMOUNT oneOf: - type: string enum: - PERCENT description: Percentage of discount used in invoice item or in an invoice. - type: string enum: - AMOUNT description: An absolute value of discount used in invoice item or in an invoice based on the currency in invoice. conditional_rule_conditions: title: conditional_rule_conditions description: Defines the time-based condition that triggers the application of this conditional rule. This is expressed as a period relative to either the invoice issue date (for early payment discounts) or the invoice due date (for late payment surcharges and auto-cancellation). If the value is 'SPECIFIC_DATE', the 'effective_date' field must be provided to specify the exact date. type: string enum: - THREE_DAYS_AFTER_ISSUE_DATE - SEVEN_DAYS_AFTER_ISSUE_DATE - FIFTEEN_DAYS_AFTER_ISSUE_DATE - THIRTY_DAYS_AFTER_ISSUE_DATE - ONE_DAY_AFTER_DUE_DATE - SEVEN_DAYS_AFTER_DUE_DATE - FIFTEEN_DAYS_AFTER_DUE_DATE - THIRTY_DAYS_AFTER_DUE_DATE - SPECIFIC_DATE oneOf: - type: string enum: - THREE_DAYS_AFTER_ISSUE_DATE description: The rule expires 3 days after the invoice issue date. Applicable for early payment discount rules. - type: string enum: - SEVEN_DAYS_AFTER_ISSUE_DATE description: The rule expires 7 days after the invoice issue date. Applicable for early payment discount rules. - type: string enum: - FIFTEEN_DAYS_AFTER_ISSUE_DATE description: The rule expires 15 days after the invoice issue date. Applicable for early payment discount rules. - type: string enum: - THIRTY_DAYS_AFTER_ISSUE_DATE description: The rule expires 30 days after the invoice issue date. Applicable for early payment discount rules. - type: string enum: - ONE_DAY_AFTER_DUE_DATE description: The rule takes effect 1 day after the invoice due date. Applicable for late payment surcharge and auto-cancellation rules. - type: string enum: - SEVEN_DAYS_AFTER_DUE_DATE description: The rule takes effect 7 days after the invoice due date. Applicable for late payment surcharge and auto-cancellation rules. - type: string enum: - FIFTEEN_DAYS_AFTER_DUE_DATE description: The rule takes effect 15 days after the invoice due date. Applicable for late payment surcharge and auto-cancellation rules. - type: string enum: - THIRTY_DAYS_AFTER_DUE_DATE description: The rule takes effect 30 days after the invoice due date. Applicable for late payment surcharge and auto-cancellation rules. - type: string enum: - SPECIFIC_DATE description: The rule expires or takes effect on a specific date provided in the `condition_rule_end_date` field. Applicable for all conditional rule types. rule_expiry_terms: title: conditional_rules description: The expiry terms that define when a conditional rule on an invoice expires, including the expiry condition and the end date. type: object required: - condition_rule_end_date - rule_expiry_condition properties: rule_expiry_condition: $ref: "#/components/schemas/conditional_rule_conditions" condition_rule_end_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The calculated end date for the conditional rule based on the rule_expiry_condition. This date indicates when the rule will expire or take effect. Specified in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Only UTC is supported in response. For example, `2025-03-12T00:00:00Z`. rules: title: rules description: The conditional rule fields that define automated actions or adjustments applied by the merchant to an invoice, such as early payment discounts or auto cancellation. type: object required: - conditional_rule_type - rule_expiry_terms properties: conditional_rule_id: allOf: - $ref: "#/components/schemas/conditional_rule_time_based_uuid" - description: The unique identifier for the conditional rule. readOnly: true conditional_rule_type: allOf: - $ref: "#/components/schemas/conditional_rule_type" - description: The type of conditional rule applied to the invoice. conditional_rule_value: description: Represents the value of the conditional rule it can be a percentage or absolute value. In case of absolute value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). type: string minLength: 1 maxLength: 32 pattern: ^(([0-9]+)|(([0-9]+)?[.][0-9]+))$ conditional_rule_value_type: allOf: - $ref: "#/components/schemas/conditional_rule_value_type" - description: The value type that indicates how the conditional rule value is applied. Use `PERCENT` for a percentage-based discount or `AMOUNT` for an absolute currency value. discount_id: title: Stored Discount ID description: The unique identifier for the stored discount that is created when an early payment discount rule is applied to an invoice. type: string minLength: 1 maxLength: 22 pattern: ^DISC-[A-Z0-9]+$ readOnly: true discount_name: description: Represents the name of the stored discount. type: string minLength: 1 maxLength: 40 pattern: ^[a-zA-Z0-9\s]+$ readOnly: true rule_expiry_terms: $ref: "#/components/schemas/rule_expiry_terms" create_time: allOf: - $ref: "#/components/schemas/date_time" - description: Indicates time of rule creation. readOnly: true update_time: allOf: - $ref: "#/components/schemas/date_time" - description: Indicates time of rule update. readOnly: true links: description: HATEOAS links. type: array minItems: 1 maxItems: 10 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" conditional_rule: title: Conditional Rule description: The conditional rule associated with an invoice that defines automated actions or adjustments that apply to an invoice based on specific conditions, such as early payment discounts, or auto cancellation. type: object allOf: - $ref: "#/components/schemas/rules" - type: object properties: links: description: HATEOAS link of the created resource. type: array minItems: 1 maxItems: 8 readOnly: true items: $ref: "#/components/schemas/link_description" conditional_rules: title: Conditional Rules description: The conditional rules associated with an invoice. Conditional rules define automated actions or adjustments that apply to an invoice based on specific conditions, such as early payment discounts, or auto cancellation. type: object properties: rules: description: The list of conditional rules created by the merchant. type: array minItems: 1 maxItems: 5 readOnly: true items: allOf: - $ref: "#/components/schemas/rules" - description: Individual conditional rule definition. links: description: HATEOAS link of the created resource. type: array minItems: 1 maxItems: 8 readOnly: true items: $ref: "#/components/schemas/link_description" recurring_status: description: The lifecycle status of a recurring invoice series. Determines the operational state and whether invoices are actively being generated. type: string enum: - DRAFT - ACTIVE - CANCELLED - EXPIRED readOnly: true oneOf: - type: string enum: - DRAFT description: The recurring series is in draft state. No invoices are generated or sent until the series is activated. The series configuration can be edited while in draft status. - type: string enum: - ACTIVE description: The recurring series is active and operational. Invoices are automatically generated and sent to recipients according to the configured schedule and payment plan. - type: string enum: - CANCELLED description: The recurring series has been canceled and is no longer active. No additional invoices will be generated or sent. This action is typically irreversible. - type: string enum: - EXPIRED description: The recurring series has reached its scheduled end date or maximum number of invoices and is now expired. No additional invoices will be generated or sent. plan_frequency: title: plan_frequency description: The frequency of the recurring invoice series cycle. type: object required: - interval_count - interval_unit properties: interval_unit: description: The time unit for the recurring invoice cycle interval. Used together with interval_count to determine the frequency of invoice generation. type: string enum: - DAY - WEEK - MONTH - YEAR oneOf: - type: string enum: - DAY description: A daily cycle. - type: string enum: - WEEK description: A weekly cycle. - type: string enum: - MONTH description: A monthly cycle. - type: string enum: - YEAR description: A yearly cycle. interval_count: description: The number of intervals between each recurring invoice cycle. For example, an interval_count of 2 with interval_unit of MONTH means the invoice recurs every 2 months. type: integer minimum: 1 maximum: 52 default: 1 plan: title: plan description: The scheduling and recurrence configuration that defines when and how often invoices are automatically generated and sent to customers in a recurring series. type: object required: - frequency properties: total_cycles: description: "The total number of billing cycles (invoices) that will be generated in this recurring series. Once all cycles are completed, the series automatically expires. Note: if not set, then the series will be indefinite." type: integer minimum: 0 maximum: 99 frequency: allOf: - $ref: "#/components/schemas/plan_frequency" - description: The billing frequency that determines the time interval between successive invoice generations. Defines how often invoices are sent to the customer (e.g., weekly, monthly, yearly). start_series_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: "The date when the recurring series begins and the first invoice is generated. Must be specified in yyyy-MM-DD format and cannot be a past date. The start date must be either today or a future date. Note: If it is not explicitly passed then the system will assume current date as start series date." next_occurrence_date: allOf: - $ref: "#/components/schemas/date_no_time" - description: The calculated date when the next invoice in the series will be automatically generated and sent. This date is determined based on the frequency and the last invoice sent date. readOnly: true completed_cycles: description: The number of billing cycles (invoices) that have already been generated and sent in this recurring series. This counter increments with each invoice sent and helps track progress toward the total cycles. type: integer minimum: 0 maximum: 2147483647 readOnly: true recurring_series_detail: title: recurring_series_detail description: The detailed information for a recurring invoice series, including payment terms and other configuration settings. type: object allOf: - $ref: "#/components/schemas/detail" - type: object properties: payment_term: allOf: - $ref: "#/components/schemas/payment_term" - description: The payment terms that define when payment is due for invoices in this series. recurring_configuration: title: configuration description: The invoice configuration details. Includes partial payment, tip, and tax calculated after discount. type: object allOf: - $ref: "#/components/schemas/base_configuration" - type: object properties: template_id: description: The template ID. The template determines the layout of the invoice.
You can either use an existing template ID or create a new template via the create template API and then use the newly created template's ID.
type: string minLength: 22 maxLength: 22 pattern: ^(TEMP-)[A-Z0-9]+$ default: PayPal system template recurring_info: title: recurring_info description: Comprehensive information about a recurring invoice series, including invoice details, participant information, line items, and amount calculations. type: object required: - detail - primary_recipients properties: detail: allOf: - $ref: "#/components/schemas/recurring_series_detail" - description: The recurring series configuration details, including payment terms and scheduling information. invoicer: allOf: - $ref: "#/components/schemas/invoicer_info" - description: The merchant or business information for the party issuing the recurring invoices. Includes business name, contact details (email, address, phone, fax), tax identification number, additional notes, and logo URL. primary_recipients: description: The primary recipient of the recurring invoices. Contains billing and shipping information including the recipient's name, email address, physical address, phone number, and preferred language. type: array minItems: 1 maxItems: 1 items: allOf: - $ref: "#/components/schemas/recipient_info" - title: primary_recipient additional_recipients: description: Additional email addresses to receive carbon copy (CC) notifications when invoices in this series are sent. type: array minItems: 1 maxItems: 100 items: allOf: - $ref: "#/components/schemas/email_address" - title: additional_recipient items: description: The line items that will appear on each invoice in the recurring series. Each item includes product or service details, quantity, unit price, and any applicable discounts or taxes. type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/item" configuration: allOf: - $ref: "#/components/schemas/recurring_configuration" - description: Configuration settings for invoices in this series. Defines whether partial payments are allowed, tip options, and whether tax is calculated before or after applying discounts. amount: allOf: - $ref: "#/components/schemas/amount_summary_detail" - description: "The calculated amount breakdown for each invoice in the series, including subtotal of all items, total discounts applied, tax amounts, and shipping costs. Note: Only invoice-level discount, shipping, and custom amounts are accepted. The rest of the fields are not mandatory and are ignored if set. They are automatically computed irrespective of the values set in the request." recurring_metadata: title: recurring_metadata description: Comprehensive audit and tracking metadata that captures key lifecycle events and actions performed on the recurring invoice series, including creation, updates and cancellation. type: object readOnly: true allOf: - $ref: "#/components/schemas/template_metadata" - type: object properties: canceled_time: allOf: - $ref: "#/components/schemas/date_time" - description: The date and time when the recurring series was canceled, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Only populated if the series has been cancelled. readOnly: true recurring_series: title: recurring_series description: A recurring invoice series that automatically generates and sends invoices to customers on a scheduled basis. Contains all configuration, status, and metadata for the series. type: object required: - plan_detail - recurring_info properties: id: description: The unique identifier for the recurring invoice series. This ID is used to reference and manage the series in all API operations. type: string minLength: 20 maxLength: 20 pattern: ^(RI-)[A-Z0-9]+$ readOnly: true status: $ref: "#/components/schemas/recurring_status" plan_detail: $ref: "#/components/schemas/plan" recurring_info: $ref: "#/components/schemas/recurring_info" metadata: allOf: - $ref: "#/components/schemas/recurring_metadata" - description: Audit and tracking information for the recurring series, including creation timestamp, last update timestamp and cancellation information if applicable. links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 1 maxItems: 5 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" - title: link_description reminder_type: description: The type of the auto reminder configuration. type: string enum: - BEFORE_DUE - AFTER_DUE oneOf: - type: string enum: - BEFORE_DUE description: Represents the auto reminder configuration for invoices prior to their due date. - type: string enum: - AFTER_DUE description: Represents the auto reminder configuration for invoices after their due date. reminder_status: description: The status of the auto reminder configuration. type: string enum: - ACTIVE - INACTIVE readOnly: true oneOf: - type: string enum: - ACTIVE description: Specifies the configuration is active. - type: string enum: - INACTIVE description: Specifies the configuration is inactive. reminder_interval_unit: description: Defines the recurrence unit of time for sending automatic reminders. type: string enum: - DAY oneOf: - type: string enum: - DAY description: Reminders are sent daily. reminder_interval: title: Invoice auto reminder interval description: Defines the time interval used to determine when a reminder is sent relative to the invoice due date. The interval consists of a unit (for example, DAY) and a numeric value that specifies how many units before or after the due date the reminder is triggered. type: object required: - unit - value properties: unit: $ref: "#/components/schemas/reminder_interval_unit" value: description: The number of time units before or after the invoice due date when the reminder is sent. Minimum value is 1 and maximum value is 7. type: integer minimum: 1 maximum: 7 reminder_notification: title: Notification description: The email notification to send to the invoicer or payer on auto reminder configuration. type: object properties: send_to_invoicer: description: Indicates whether to send a copy of the email to the merchant. type: boolean default: false reminder_metadata: title: Invoice auto reminder configuration metadata. description: Invoice auto reminder configuration metadata. type: object properties: created_time: allOf: - $ref: "#/components/schemas/date_time" - description: Represents the date and time at which this auto reminder configuration was created. readOnly: true updated_time: allOf: - $ref: "#/components/schemas/date_time" - description: Represents the date and time at which this auto reminder configuration was last updated. readOnly: true invoice_reminder_configuration: title: invoice_reminder_configuration description: Invoice reminder configuration object to specify the frequency, reminder type and other params related to invoice auto reminder configuration. type: object required: - interval - repetition - type properties: id: description: Represents the auto reminder configuration id. type: string minLength: 20 maxLength: 20 pattern: ^RC-[A-Z0-9]+$ readOnly: true type: $ref: "#/components/schemas/reminder_type" status: $ref: "#/components/schemas/reminder_status" interval: $ref: "#/components/schemas/reminder_interval" repetition: description: "The repetition at which the auto reminder has to be set. Note: For `BEFORE_DUE` reminder type, repetition is always one." type: integer minimum: 1 maximum: 7 notification: $ref: "#/components/schemas/reminder_notification" metadata: $ref: "#/components/schemas/reminder_metadata" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 1 maxItems: 4 readOnly: true items: $ref: "#/components/schemas/link_description" invoice_auto_reminder_config_setup: title: invoice_auto_reminder_config_setup description: Request body for initializing invoice auto reminder configuration. The request may include up to two reminder configurations (BEFORE_DUE and AFTER_DUE), which will be applied to all invoices created by the merchant. If only one reminder type is provided, the missing reminder type will be created using the default configuration in INACTIVE state. If the request body is empty, both reminder types will be created using the default configuration in INACTIVE state. Reminder configurations created using the provided payload are set to ACTIVE state. type: object properties: configurations: description: An array of invoice auto reminder configurations. The array can contain a maximum of two configurations, one for BEFORE_DUE reminder type and one for AFTER_DUE reminder type. type: array minItems: 1 maxItems: 2 items: $ref: "#/components/schemas/invoice_reminder_configuration" invoice_reminder_configurations: title: invoice_reminder_configurations description: List of invoice reminder configurations. type: object properties: configurations: description: An array of invoice auto reminder configurations. type: array minItems: 1 maxItems: 2 items: $ref: "#/components/schemas/invoice_reminder_configuration" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 1 maxItems: 4 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" - readOnly: true recurring_series_free_text_search_fields: description: Supported recurring invoices series free text search fields. type: string enum: - NOTES - MERCHANT_MEMO - PAYER_REFERENCE_INFO - BILLING_EMAIL - BILLING_NAME - BILLING_BUSINESS_NAME - BILLING_PHONE_NUMBER - SHIPPING_NAME - SHIPPING_BUSINESS_NAME - SHIPPING_PHONE_NUMBER - ITEM_NAME - ITEM_TAX_NAME - ITEM_DISCOUNT_NAME - INVOICE_DISCOUNT_NAME - ALL oneOf: - type: string enum: - NOTES description: Notes associated with the recurring invoices series. - type: string enum: - MERCHANT_MEMO description: Merchant memo related to the recurring invoices series. - type: string enum: - PAYER_REFERENCE_INFO description: Payer's reference information. - type: string enum: - BILLING_EMAIL description: Email address associated with billing. - type: string enum: - BILLING_NAME description: Name associated with billing. - type: string enum: - BILLING_BUSINESS_NAME description: Business name associated with billing. - type: string enum: - BILLING_PHONE_NUMBER description: Phone number associated with billing. - type: string enum: - SHIPPING_NAME description: Name associated with shipping. - type: string enum: - SHIPPING_BUSINESS_NAME description: Business name associated with shipping. - type: string enum: - SHIPPING_PHONE_NUMBER description: Phone number associated with shipping. - type: string enum: - ITEM_NAME description: Name of the recurring invoices series item. - type: string enum: - ITEM_TAX_NAME description: Tax name associated with the recurring invoices series item. - type: string enum: - ITEM_DISCOUNT_NAME description: Discount name associated with the recurring invoices series item. - type: string enum: - INVOICE_DISCOUNT_NAME description: Discount name associated with the recurring invoices series. - type: string enum: - ALL description: Search in all available search fields. recurring_series_search_filters: title: Search filters properties. description: "Search filters - to retrieve recurring invoices series.
Note:This API currently supports only one criterion for range queries, so specify only one of the following criteria: creation_date_range or next_occurrence_date_range.
" type: object properties: currency_code: $ref: "#/components/schemas/currency_code" status: description: An array of recurring invoice series status. type: array minItems: 1 maxItems: 5 uniqueItems: true items: $ref: "#/components/schemas/recurring_status" archived: description: Indicates whether to list merchant-archived recurring invoice series in the response. If 'true', the response lists only merchant-archived invoices. If 'false', the response lists only unarchived invoices. If 'null', the response defaults to false. type: boolean creation_date_range: $ref: "#/components/schemas/date_time_range" next_occurrence_date_range: $ref: "#/components/schemas/date_range" total_amount_range: $ref: "#/components/schemas/amount_range" recurring_series_search_data: title: Search criteria - to search recurring invoices series. description: Search criteria - to search recurring invoices series. type: object properties: search_text: description: Describes the search text, which will be used to check if this particular search_text present in any of the recurring invoice series fields, specified by search_fields. type: string minLength: 3 maxLength: 800 pattern: ^(?!\s*$).+$ search_fields: description: Describes the set of fields on which the search will be performed.
Note:
type: array minItems: 1 maxItems: 5 uniqueItems: true items: $ref: "#/components/schemas/recurring_series_free_text_search_fields" search_filters: $ref: "#/components/schemas/recurring_series_search_filters" multiple_recurring_series: title: Search recurring invoices series - response object. description: An array of merchant recurring invoices series. It includes [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links) for navigation. type: object properties: recurring_invoices: description: The list of recurring invoices series that match the search criteria. type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/recurring_series" links: description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 1 maxItems: 4 readOnly: true items: allOf: - $ref: "#/components/schemas/link_description" parameters: authorization: name: Authorization in: header description: Holds authorization information for external API calls. required: false schema: $ref: "#/components/schemas/standard_header_schema" examples: bearer: summary: Bearer authorization. description: An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example. value: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ paypal_request_id: name: PayPal-Request-Id in: header description: A unique ID identifying the request header for idempotency purposes. required: false schema: description: A unique ID identifying the request header for idempotency purposes. type: string minLength: 1 maxLength: 10000 pattern: ^.*$ examples: request_id: summary: A request id. description: A paypal-request-id header with a randomized value. value: 17e81d06-77ab-11e8-adc0-fa71639ebebc responses: default_response: description: Default response. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Default response. description: Example catch all response, should not be encountered in practice. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. 401_error_response: description: Unauthorized. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Generic 'Unauthorized' error. description: Example response for unauthorized request. value: name: AUTHENTICATION_FAILURE debug_id: b1d1f06c7246c message: Authentication failed due to missing Authorization header, or invalid authentication credentials. 403_error_response: description: Forbidden. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Generic 'Forbidden' error. description: Example response for a forbidden request. value: name: NOT_AUTHORIZED debug_id: b1d1f06c7246c message: Authorization failed due to insufficient permissions. 500_error_response: description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/error" examples: generic: summary: Generic internal server error. description: Example response for a request that fails for reasons internal to the server. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. 204_response: description: No Content.