{ "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/libaddressinput/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." } } } }