{ "openapi": "3.0.3", "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.7", "contact": {} }, "servers": [ { "url": "https://api-m.sandbox.paypal.com", "description": "PayPal Sandbox Environment" }, { "url": "https://api-m.paypal.com", "description": "PayPal Live Environment" } ], "tags": [ { "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": "search-invoices", "description": "Use the `/search-invoices` resource to search for and list invoices that match search criteria." }, { "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.
" }, { "name": "merchant-config", "description": "Use the `/merchant-config` resource to create, update and show details of merchant configuration." }, { "name": "estimates", "description": "Use the /estimate resource to create, update, and send estimates." }, { "name": "batch-tasks", "description": "Use the /batch-tasks resource to create, delete and retrieve batch related tasks." }, { "name": "stored-discounts", "description": "Use the /stored-discounts resource to create and retrieve stored-discounts are specific 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": "Invoicing Multi Tenancy", "description": "This section contains api to get the tenant config details." }, { "name": "Invoice Notification", "description": "Use the /email-status-feedback resource to post the status update against invoicing emails." }, { "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 retrieve aggregated metrics specific to merchants." }, { "name": "invoicing-product-features", "description": "This section contains the list of invoicing-product-features related api's." }, { "name": "conditional-rules", "description": "This section contains api's related to conditional rules." }, { "name": "invoice-payment-attempt", "description": "This section contains api's related to invoice payment attempt." }, { "name": "connections", "description": "Use the `accounting-sync/merchants/connections` resource to get active connections list." }, { "name": "invoice-connection-details", "description": "Use the `accounting-sync/invoices/{id}/connections` resource to get active connections list." }, { "name": "Invoicing themes", "description": "Use the /themes resource to create, update and get details of themes related to merchants." }, { "name": "Bulk Sync Invoices - Accounting Sync", "description": "Use the /accounting-invoices-batch resource to bulk sync invoices with accounting software." }, { "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": "Accounting sync", "description": "This section contains invoicing APIs related to accounting sync." } ], "externalDocs": { "url": "https://developer.paypal.com/docs/api/invoicing/v2/" }, "paths": { "/v2/invoicing/invoices": { "post": { "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.
.", "operationId": "invoices.create", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/invoice" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.create-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.create-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" } } }, "description": "The invoice details which includes all information of the invoice like items, billing information.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] }, "get": { "summary": "List invoices", "description": "Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.", "operationId": "invoices.list", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/invoices" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/total_required" }, { "$ref": "#/components/parameters/fields" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/send": { "post": { "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:
", "operationId": "invoices.send", "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" } }, "multipart/mixed": { "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/link_description" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_422" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_422" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification" } } }, "description": "The email or SMS notification to send to the payer when they send an invoice.." }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/remind": { "post": { "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:
.", "operationId": "invoices.remind", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.remind-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.remind-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.remind-422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.remind-422" } ] } } } }, "429": { "description": "Too many requests. Blocked due to rate limiting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_429" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_429" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification" } } }, "description": "The email or SMS notification that will be sent to the payer for reminder." }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/cancel": { "post": { "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.", "operationId": "invoices.cancel", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.cancel-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.cancel-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification" } } }, "description": "The email or SMS notification that will be sent to the payer on cancellation.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/payments": { "post": { "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`.", "operationId": "invoices.payments", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/payment_reference" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.payments-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.payments-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.payments-422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.payments-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_detail" } } }, "description": "The details of the payment to record against the invoice.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}": { "delete": { "summary": "Delete external payment", "description": "Deletes an external payment, by invoice ID and transaction ID.", "operationId": "invoices.payments-delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.payments-delete-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/transaction_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/refunds": { "post": { "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`.", "operationId": "invoices.refunds", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/refund_reference" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.refunds-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.refunds-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.refunds-422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.refunds-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_detail" } } }, "description": "The details of the refund to record against the invoice.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}": { "delete": { "summary": "Delete external refund", "description": "Deletes an external refund, by invoice ID and transaction ID.", "operationId": "invoices.refunds-delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/transaction_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}/generate-qr-code": { "post": { "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.", "operationId": "invoices.generate-qr-code", "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": { "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.generate-qr-code-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qr_config" }, "examples": { "0": { "$ref": "#/components/examples/qr_config" } } } }, "description": "Optional configuration parameters to adjust QR code width, height and the encoded URL." }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/generate-next-invoice-number": { "post": { "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`.", "operationId": "invoicing.generate-next-invoice-number", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fetchtype" } } }, "description": "Is the fetch type invoice number or id." }, "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_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/invoices/{invoice_id}": { "get": { "summary": "Show invoice details", "description": "Shows details for an invoice, by ID.", "operationId": "invoices.get", "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" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read" ] } ], "tags": [ "invoices" ] }, "put": { "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:
.", "operationId": "invoices.update", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/invoice" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.update-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.update-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.update-422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/invoices.update-422" } ] } } } }, "429": { "description": "Too many requests. Blocked due to rate limiting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_429" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_429" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/send_to_recipient" }, { "$ref": "#/components/parameters/send_to_invoicer" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" } } }, "description": "A representation of changes to make in the invoice.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "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.", "operationId": "invoices.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "invoices" ] } }, "/v2/invoicing/search-invoices": { "post": { "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.", "operationId": "invoices.search-invoices", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/invoices" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.search-invoices-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/invoices.search-invoices-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/total_required" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_data" } } }, "description": "The invoice search can be used to retrieve the invoices based on the search parameters." }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read" ] } ], "tags": [ "search-invoices" ] } }, "/v2/invoicing/templates": { "get": { "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.", "operationId": "templates.list", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/templates" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read" ] } ], "tags": [ "templates" ] }, "post": { "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`.
", "operationId": "templates.create", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/template" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/templates.create-400" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/templates.create-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/templates.create-422" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/templates.create-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } }, "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "templates" ] } }, "/v2/invoicing/templates/{template_id}": { "get": { "summary": "Show template details", "description": "Shows details for a template, by ID.", "operationId": "templates.get", "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" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/template" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/templates.get-403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/templates.get-403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read" ] } ], "tags": [ "templates" ] }, "put": { "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.", "operationId": "templates.update", "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": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/templates.update-400" } ] } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } }, "description": "A representation of changes to make in the template.", "required": true }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "templates" ] }, "delete": { "summary": "Delete template", "description": "Deletes a template, by ID.", "operationId": "templates.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/templates.delete-403" } ] } }, "multipart/mixed": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/templates.delete-403" } ] } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/readwrite" ] } ], "tags": [ "templates" ] } }, "/v2/invoicing/accounting-sync/merchant/connections": { "get": { "summary": "List Connections.", "description": "Lists connections to accounting platforms per merchant.", "operationId": "connections.get", "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/connections" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read", "https://uri.paypal.com/services/invoicing/invoices/readwrite", "https://uri.paypal.com/services/invoicing/internal" ] } ], "tags": [ "connections" ] } }, "/v2/invoicing/accounting-sync/invoices/{id}/connections": { "get": { "summary": "List Connection Status for an Invoice.", "description": "Lists connections to accounting platforms per invoice.", "operationId": "invoice_connection_details.get", "parameters": [ { "$ref": "#/components/parameters/id" } ], "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_connection_details" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_400" } } } }, "403": { "description": "Authorization Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_403" } } } }, "404": { "description": "Resource Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing/invoices/read", "https://uri.paypal.com/services/invoicing/invoices/readwrite", "https://uri.paypal.com/services/invoicing/internal" ] } ], "tags": [ "invoice-connection-details" ] } } }, "components": { "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/v1/oauth2/token", "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." } } } } }, "responses": { "default": { "description": "The default response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_default" } } } } }, "schemas": { "400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "Value exceeds max value." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "Value less than minimum value." ] } } } ] } } } }, "403": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "PERMISSION_DENIED", "properties": { "issue": { "type": "string", "enum": [ "PERMISSION_DENIED" ] }, "description": { "type": "string", "enum": [ "The requested invoice is not associated with the requested user." ] } } } ] } } } }, "422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_NOT_FOUND", "properties": { "issue": { "type": "string", "enum": [ "USER_NOT_FOUND" ] }, "description": { "type": "string", "enum": [ "User is not associated with paypal based on invoicer email." ] } } } ] } } } }, "address_details": { "type": "object", "title": "Address Details", "description": "The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. 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`.", "properties": { "street_number": { "type": "string", "description": "The street number.", "maxLength": 100 }, "street_name": { "type": "string", "description": "The street name. Just `Drury` in `Drury Lane`.", "maxLength": 100 }, "street_type": { "type": "string", "description": "The street type. For example, avenue, boulevard, road, or expressway.", "maxLength": 100 }, "delivery_service": { "type": "string", "description": "The delivery service. Post office box, bag number, or post office name.", "maxLength": 100 }, "building_name": { "type": "string", "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.", "maxLength": 100 }, "sub_building": { "type": "string", "description": "The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.", "maxLength": 100 } } }, "address_portable": { "type": "object", "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).", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address. For example, suite or apartment number.", "maxLength": 300 }, "address_line_3": { "type": "string", "description": "The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address.", "maxLength": 100 }, "admin_area_4": { "type": "string", "description": "The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:", "maxLength": 100 }, "admin_area_3": { "type": "string", "description": "A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:", "maxLength": 100 }, "admin_area_2": { "type": "string", "description": "A city, town, or village. Smaller than `admin_area_level_1`.", "maxLength": 120 }, "admin_area_1": { "type": "string", "description": "The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` and not `California`. Value, by country, is:", "maxLength": 300 }, "postal_code": { "type": "string", "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).", "maxLength": 60 }, "country_code": { "$ref": "#/components/schemas/country_code" }, "address_details": { "$ref": "#/components/schemas/address_details" } }, "required": [ "country_code" ] }, "address_portable_list": { "type": "array", "description": "An array of addresses in the user's PayPal profile.", "items": { "$ref": "#/components/schemas/address_portable" }, "readOnly": true, "minItems": 0, "maxItems": 2147483647 }, "aggregated_discount": { "type": "object", "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.", "properties": { "invoice_discount": { "$ref": "#/components/schemas/discount", "description": "The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total." }, "item_discount": { "$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." } } }, "amount_range": { "type": "object", "title": "Amount Range", "description": "The amount range.", "properties": { "lower_amount": { "$ref": "#/components/schemas/money", "description": "The lower limit of the amount range." }, "upper_amount": { "$ref": "#/components/schemas/money", "description": "The upper limit of the amount range." } }, "required": [ "lower_amount", "upper_amount" ] }, "amount_summary_detail": { "type": "object", "title": "Invoice Amount Summary", "description": "The invoice amount summary of item total, discount, tax total, and shipping.", "properties": { "currency_code": { "$ref": "#/components/schemas/currency_code" }, "value": { "type": "string", "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/).", "minLength": 0, "maxLength": 32, "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" }, "breakdown": { "$ref": "#/components/schemas/amount_with_breakdown", "description": "The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any." } } }, "amount_with_breakdown": { "type": "object", "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.", "properties": { "item_total": { "$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", "description": "The discount can be at the item or invoice level, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent." }, "tax_total": { "$ref": "#/components/schemas/money", "description": "The aggregated amount of the item and shipping taxes." }, "shipping": { "$ref": "#/components/schemas/shipping_cost", "description": "The shipping fee for all items. Includes tax on shipping." }, "custom": { "$ref": "#/components/schemas/custom_amount", "description": "The custom amount to apply to an invoice. If you include a label, you must include the custom amount." } } }, "billing_info": { "type": "object", "title": "Billing Information", "description": "The billing information of the invoice recipient. Includes name, address, email, phone, and language.", "allOf": [ { "$ref": "#/components/schemas/contact_name_address" }, { "properties": { "email_address": { "$ref": "#/components/schemas/restrictive_email_address", "description": "The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent." }, "phones": { "$ref": "#/components/schemas/definitions-phone_detail_list" }, "additional_info": { "type": "string", "description": "Any additional information about the recipient.", "maxLength": 40 }, "language": { "$ref": "#/components/schemas/language", "description": "The language in which to show the invoice recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account." } } } ] }, "business_name": { "type": "object", "title": "Business Name", "description": "The business name of the party.", "properties": { "business_name": { "type": "string", "description": "Required. The business name of the party.", "maxLength": 300 } } }, "configuration": { "type": "object", "title": "Configuration", "description": "The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.", "allOf": [ { "$ref": "#/components/schemas/template_configuration" }, { "properties": { "template_id": { "type": "string", "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.
", "default": "PayPal system template", "maxLength": 30 } } } ] }, "connection": { "type": "object", "title": "Connections", "description": "This lists last sync status and connection platform name.", "properties": { "platform_name": { "type": "string", "description": "The name of the platform. This property supports Unicode. The pattern is not provided because the value is defined by an external party.", "minLength": 1, "maxLength": 64, "pattern": "^.*$" }, "last_sync_time": { "$ref": "#/components/schemas/date_time", "description": "The date and time when the resource is last synced with the accounting platform. This property supports Unicode." }, "last_sync_status": { "type": "string", "description": "The status of the last sync. This property supports Unicode.", "minLength": 1, "maxLength": 255, "pattern": "^[A-Z0-9_]+$", "x-enumDescriptions": [ { "value": "IN_PROGRESS", "description": "The last sync process has started." }, { "value": "SUCCESS", "description": "The last sync process is success." }, { "value": "FAILED", "description": "The last sync process failed." } ], "enum": [ "IN_PROGRESS", "SUCCESS", "FAILED" ] } } }, "connection_list": { "type": "array", "description": "An array of connection-level details.", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/connection" } }, "connections": { "type": "object", "title": "Connections", "description": "This object contains an array of connection details. It is used to load sync status for a user.", "properties": { "connections": { "$ref": "#/components/schemas/connection_list" } } }, "connections_list": { "type": "array", "description": "An array of connection-level details.", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/connections" } }, "contact_name_address": { "type": "object", "title": "Contact Information", "description": "The contact information of the user. Includes name and address.", "allOf": [ { "$ref": "#/components/schemas/business_name" }, { "properties": { "name": { "$ref": "#/components/schemas/name", "description": "The first and Last name of the recipient." }, "address": { "$ref": "#/components/schemas/address_portable", "description": "The address of the recipient." } } } ] }, "country_code": { "type": "string", "description": "The [two-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.
", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.", "type": "string", "minLength": 3, "maxLength": 3, "x-security-classification": { "data_class": "class4", "data_category": "INTRINSIC" } }, "custom_amount": { "type": "object", "title": "Custom Amount", "description": "The custom amount to apply to an invoice. If you include a label, you must include a custom amount.", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The label to the custom amount of the invoice.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 50 }, "amount": { "$ref": "#/components/schemas/money", "description": "The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places." } } }, "date_no_time": { "type": "string", "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.", "format": "ppaas_date_notime_v2", "minLength": 10, "maxLength": 10, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$" }, "date_range": { "type": "object", "title": "Date Range", "description": "The date range. Filters invoices by creation date, invoice date, due date, and payment date.", "properties": { "start": { "$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": { "$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." } }, "required": [ "start", "end" ] }, "date_time": { "type": "string", "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.
", "format": "ppaas_date_time_v3", "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})$" }, "date_time_range": { "type": "object", "title": "Date and Time Range", "description": "The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.", "properties": { "start": { "$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": { "$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})$" } }, "required": [ "start", "end" ] }, "definitions-item_list": { "type": "array", "description": "An array of invoice line-item information.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/item" } }, "definitions-phone_detail_list": { "type": "array", "items": { "$ref": "#/components/schemas/phone_detail" }, "description": "The invoice recipient's phone numbers. Extension number is not supported." }, "definitions-recipient_info_list": { "type": "array", "items": { "$ref": "#/components/schemas/recipient_info" }, "minItems": 0, "maxItems": 100, "description": "The billing and shipping information. Includes name, email, address, phone, and language." }, "detail": { "title": "Invoice_Detail", "description": "The details of the invoice like notes, terms and conditions, memo, attachments.", "required": [ "currency_code" ], "properties": { "reference": { "type": "string", "description": "The reference data. Includes a Purchase Order (PO) number.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 120 }, "currency_code": { "$ref": "#/components/schemas/currency_code", "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency." }, "note": { "type": "string", "description": "A note to the invoice recipient. Also appears on the invoice notification email.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 4000 }, "terms_and_conditions": { "type": "string", "description": "The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 4000 }, "memo": { "type": "string", "description": "A private bookkeeping memo for the user.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 500 }, "attachments": { "$ref": "#/components/schemas/file_reference_list" } } }, "discount": { "type": "object", "title": "Discount", "description": "The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.", "properties": { "percent": { "$ref": "#/components/schemas/percentage", "description": "The discount as a percentage value. Value is from `0` to `100`. Supports up to five decimal places." }, "amount": { "$ref": "#/components/schemas/money", "description": "The invoice level discount amount. Value is from `0` to `1000000`. Supports up to two decimal places." } } }, "email_address": { "type": "string", "description": "The internationalized email address.
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.
", "format": "ppaas_common_email_address_v2", "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])+)\\])$" }, "email_address_list": { "type": "array", "minItems": 0, "maxItems": 100, "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.
", "items": { "$ref": "#/components/schemas/email_address" } }, "error_400": { "type": "object", "title": "Bad Request Error", "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "properties": { "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_401": { "type": "object", "title": "Unauthorized Error", "description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "properties": { "name": { "type": "string", "enum": [ "AUTHENTICATION_FAILURE" ] }, "message": { "type": "string", "enum": [ "Authentication failed due to missing authorization header, or invalid authentication credentials." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_403": { "type": "object", "title": "Not Authorized Error", "description": "The client is not authorized to access this resource, although it may have valid credentials. ", "properties": { "name": { "type": "string", "enum": [ "NOT_AUTHORIZED" ] }, "message": { "type": "string", "enum": [ "Authorization failed due to insufficient permissions." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_404": { "type": "object", "title": "Not found Error", "description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "The specified resource does not exist." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_409": { "type": "object", "title": "Resource Conflict Error", "description": "The server has detected a conflict while processing this request.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_CONFLICT" ] }, "message": { "type": "string", "enum": [ "The server has detected a conflict while processing this request." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_415": { "type": "object", "title": "Unsupported Media Type Error", "description": "The server does not support the request payload's media type.", "properties": { "name": { "type": "string", "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] }, "message": { "type": "string", "enum": [ "The server does not support the request payload's media type." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_422": { "type": "object", "title": "Unprocessable Entity Error", "description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_429": { "type": "object", "title": "Too many requests", "description": "Too many requests. Blocked due to rate limiting.", "properties": { "name": { "type": "string", "enum": [ "RATE_LIMIT_REACHED" ] }, "message": { "type": "string", "enum": [ "Too many requests. Blocked due to rate limiting." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "error_default": { "description": "The default error response.", "oneOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/error_409" }, { "$ref": "#/components/schemas/error_415" }, { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/error_429" }, { "$ref": "#/components/schemas/error_500" }, { "$ref": "#/components/schemas/error_503" } ] }, "error_details": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors." }, "value": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "$ref": "#/components/schemas/error_location" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "description": { "type": "string", "description": "The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value." } }, "required": [ "issue" ] }, "error_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", "minLength": 3, "maxLength": 6, "pattern": "^[A-Z]*$", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] } } }, "error_location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "enum": [ "body", "path", "query" ], "default": "body" }, "fetchtype": { "type": "object", "title": "Fetch Type", "description": "Is the fetch type invoice number or id.", "properties": { "fetch_id": { "type": "boolean", "description": "Optional to decide the number or ID.", "default": "false" } } }, "fields": { "type": "string", "description": "The name of the field.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 2147483647 }, "fields_list": { "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": { "$ref": "#/components/schemas/fields" } }, "file_reference": { "type": "object", "title": "File Reference", "description": "The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store.", "properties": { "id": { "type": "string", "description": "The ID of the referenced file.", "minLength": 1, "maxLength": 255 }, "reference_url": { "type": "string", "description": "The reference URL for the file.", "format": "uri", "minLength": 1, "maxLength": 2000 }, "content_type": { "type": "string", "description": "The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml)." }, "create_time": { "$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": { "type": "string", "description": "The size of the file, in bytes.", "pattern": "^[0-9]+$" } } }, "file_reference_list": { "type": "array", "description": "An array of PayPal IDs for the files that are attached to an invoice.", "minItems": 0, "maxItems": 2147483647, "items": { "$ref": "#/components/schemas/file_reference" } }, "invoice": { "type": "object", "title": "Invoice", "description": "The invoice details which includes all information of the invoice like items, billing information.", "required": [ "detail" ], "properties": { "id": { "type": "string", "description": "The ID of the invoice.", "readOnly": true, "pattern": "^[\\s\\S]*$", "minLength": 0, "maxLength": 30 }, "parent_id": { "type": "string", "description": "The parent ID to an invoice that defines the group invoice to which the invoice is related.", "readOnly": true, "pattern": "^[\\s\\S]*$", "minLength": 0, "maxLength": 30 }, "status": { "$ref": "#/components/schemas/invoice_status", "readOnly": true }, "detail": { "$ref": "#/components/schemas/invoice_detail", "description": "The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata." }, "invoicer": { "$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": { "$ref": "#/components/schemas/recipient_info_list" }, "additional_recipients": { "$ref": "#/components/schemas/email_address_list" }, "items": { "$ref": "#/components/schemas/item_list" }, "configuration": { "$ref": "#/components/schemas/configuration", "description": "The invoice configuration details. Includes partial payment, tip, and tax calculated after discount." }, "amount": { "$ref": "#/components/schemas/amount_summary_detail", "description": "The invoice amount summary of item total, discount, tax total and shipping.." }, "due_amount": { "description": "The due amount, which is the balance amount outstanding after payments.", "$ref": "#/components/schemas/money", "readOnly": true }, "gratuity": { "description": "The amount paid by the payer as gratuity to the invoicer.", "$ref": "#/components/schemas/money", "readOnly": true }, "payments": { "$ref": "#/components/schemas/payments", "description": "List of payments registered against the invoice.." }, "refunds": { "$ref": "#/components/schemas/refunds", "description": "List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method." }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "invoice_connection_details": { "type": "object", "title": "Invoice Connection Details", "description": "Returns invoice connection status with timestamp per invoice.", "properties": { "id": { "type": "string", "description": "The ID of the invoice. This property supports Unicode.", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9\\-]+$" }, "connection_status": { "$ref": "#/components/schemas/connections_list" } } }, "invoice_creation_flow": { "type": "string", "title": "Invoice Creation Flow", "description": "The frequency at which the invoice is sent:", "minLength": 0, "maxLength": 255, "pattern": "^[\\s\\S]*$", "x-enumDescriptions": [ { "value": "MULTIPLE_RECIPIENTS_GROUP", "description": "The invoice sent to multiple recipients." }, { "value": "BATCH", "description": "The invoice sent as a batch." }, { "value": "REGULAR_SINGLE", "description": "The regular invoice sent to single recipient." } ], "enum": [ "MULTIPLE_RECIPIENTS_GROUP", "BATCH", "REGULAR_SINGLE" ] }, "invoice_detail": { "type": "object", "title": "Invoice Detail", "description": "The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.", "allOf": [ { "$ref": "#/components/schemas/detail" }, { "properties": { "invoice_number": { "type": "string", "description": "The invoice number. Default is the number that is auto-incremented number from the last number.", "maxLength": 25 }, "invoice_date": { "$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": { "$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": { "$ref": "#/components/schemas/metadata", "description": "The audit metadata. Captures all invoicing actions on create, send, update, and cancel.", "readOnly": true } } } ] }, "invoice_list": { "type": "array", "description": "The list of invoices that match the search criteria.", "readOnly": true, "items": { "$ref": "#/components/schemas/invoice" }, "minItems": 0, "maxItems": 100 }, "invoice_number": { "type": "object", "title": "Invoice Number", "description": "The invoice number.", "properties": { "invoice_number": { "type": "string", "description": "The invoice number. If you omit this value, the default is the auto-incremented number from the last number.", "minLength": 1, "maxLength": 25, "readOnly": true, "pattern": "^[\\S\\s]*$" }, "invoice_id": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^(INV2-)[A-Z0-9\\-]{19}$", "description": "Resource Id.", "readOnly": true } } }, "invoice_payment_term": { "type": "object", "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.", "allOf": [ { "$ref": "#/components/schemas/payment_term" }, { "properties": { "due_date": { "$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*." } } } ] }, "invoice_status": { "type": "string", "title": "Invoice Status", "description": "The status of the invoice.", "minLength": 0, "maxLength": 255, "pattern": "^[\\s\\S]*$", "x-enumDescriptions": [ { "value": "DRAFT", "description": "The invoice is in draft state. It is not yet sent to the payer." }, { "value": "SENT", "description": "The invoice has been sent to the payer. The payment is awaited from the payer." }, { "value": "SCHEDULED", "description": "The invoice is scheduled on a future date. It is not yet sent to the payer." }, { "value": "PAID", "description": "The payer has paid for the invoice." }, { "value": "MARKED_AS_PAID", "description": "The invoice is marked as paid by the invoicer." }, { "value": "CANCELLED", "description": "The invoice has been cancelled by the invoicer." }, { "value": "REFUNDED", "description": "The invoice has been refunded by the invoicer." }, { "value": "PARTIALLY_PAID", "description": "The payer has partially paid for the invoice." }, { "value": "PARTIALLY_REFUNDED", "description": "The invoice has been partially refunded by the invoicer." }, { "value": "MARKED_AS_REFUNDED", "description": "The invoice is marked as refunded by the invoicer." }, { "value": "UNPAID", "description": "The invoicer is yet to receive the payment from the payer for the invoice." }, { "value": "PAYMENT_PENDING", "description": "The invoicer is yet to receive the payment for the invoice. It is under pending review." }, { "value": "AUTO_CANCELLED", "description": "The invoice was automatically cancelled because the payment was not received within the specified timeframe." }, { "value": "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." }, { "value": "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." }, { "value": "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." } ], "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" ] }, "invoice_status_list": { "type": "array", "description": "An array of status values.", "items": { "$ref": "#/components/schemas/invoice_status" }, "minItems": 0, "maxItems": 5 }, "invoicer_info": { "type": "object", "title": "Invoicer Information", "description": "The invoicer business information that appears on the invoice.", "allOf": [ { "$ref": "#/components/schemas/contact_name_address" }, { "properties": { "email_address": { "$ref": "#/components/schemas/restrictive_email_address", "description": "The invoicer email address, which must be listed in the user's PayPal profile. If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice." }, "phones": { "$ref": "#/components/schemas/phone_detail_list" }, "website": { "type": "string", "format": "uri", "description": "The invoicer's website.", "maxLength": 2048 }, "tax_id": { "type": "string", "description": "The invoicer's tax ID.", "maxLength": 100 }, "additional_notes": { "type": "string", "description": "Any additional information. Includes business hours.", "maxLength": 400 }, "logo_url": { "type": "string", "format": "uri", "description": "The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.", "maxLength": 2000 } } } ] }, "invoices": { "type": "object", "title": "Invoices", "minItems": 1, "description": "An array of merchant invoices. Includes the total invoices count and [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links) for navigation.", "properties": { "total_pages": { "type": "integer", "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
", "readOnly": true, "minimum": 0, "maximum": 2147483647 }, "total_items": { "type": "integer", "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.
", "readOnly": true, "minimum": 0, "maximum": 2147483647 }, "items": { "$ref": "#/components/schemas/invoice_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "invoices.cancel-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Field value exceeded the maximum allowed number of characters." ] } } }, { "title": "INVALID_ARRAY_MAX_ITEMS", "properties": { "issue": { "type": "string", "enum": [ "INVALID_ARRAY_MAX_ITEMS" ] }, "description": { "type": "string", "enum": [ "Only maximum of 100 email address is supported in additional recipients." ] } } } ] } } } }, "invoices.cancel-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "CANNOT_CANCEL_DRAFT_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_CANCEL_DRAFT_INVOICE" ] }, "description": { "type": "string", "enum": [ "Draft invoice cannot be canceled." ] } } }, { "title": "CANNOT_CANCEL_PAID_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_CANCEL_PAID_INVOICE" ] }, "description": { "type": "string", "enum": [ "Cannot cancel a paid or partially paid invoice." ] } } }, { "title": "CANNOT_CANCEL_REFUNDED_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_CANCEL_REFUNDED_INVOICE" ] }, "description": { "type": "string", "enum": [ "Cannot cancel a refunded or partially refunded invoice." ] } } }, { "title": "CANNOT_CANCEL_SCHEDULED_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_CANCEL_SCHEDULED_INVOICE" ] }, "description": { "type": "string", "enum": [ "Cannot cancel a scheduled invoice." ] } } }, { "title": "INVOICE_CANCELED_ALREADY", "properties": { "issue": { "type": "string", "enum": [ "INVOICE_CANCELED_ALREADY" ] }, "description": { "type": "string", "enum": [ "Invoice is already cancelled." ] } } } ] } } } }, "invoices.create-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Address line2 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "National Number length should be between 1 and 14." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Address line1 length should be less than 300 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Country code is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Custom label length should be less than 50 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Given name length should be less than 140 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Language is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Admin area1 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item quantity length should be 1 and 14." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Surname length should be less than 140 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Attachment reference url length should be between 1 and 2000." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Country code length should be 2 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Business name length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Minimum due amount length should be less than 32 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Attachment id length should be between 1 and 255." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Admin area2 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Tax name length should be less than 100." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Website url length should be less than 2048 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Postal code length should be less than 60 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "National Number is not valid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Memo length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item name length should be less than 200 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "country code length should be between 1 and 3." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Template Id length should be less than 22 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Logo url length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice note length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Reference field length should be less than 120 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Due date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Terms and Conditions length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Email address length should be between 3 and 254." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Additional data length should be less than 4000." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Additional information value length should be less than 40 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Tax id length should be less than 100 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Invoice date is invalid." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice number length should be less than 25 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Item Date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item description length should be less than 1000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Shipping Tax name length should be less than 100 characters." ] } } } ] } } } }, "invoices.generate-qr-code-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "Value exceeds max value." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "Value less than minimum value." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Value of the field does not conform to the expected format." ] } } } ] } } } }, "invoices.payments-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "Payment method is missing. Please provide a valid payment method." ] } } }, { "title": "INVALID_PAYMENT_METHOD", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PAYMENT_METHOD" ] }, "description": { "type": "string", "enum": [ "The value provided is not an acceptable method of payment." ] } } }, { "title": "NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Currency code is not supported." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "Amount value is missing. Please provide a valid amount." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Amount value cannot be greater than the maximum limit of 32 characters length." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Amount value is invalid. Should be a numeric value." ] } } }, { "title": "VALUE_CANNOT_BE_ZERO", "properties": { "issue": { "type": "string", "enum": [ "VALUE_CANNOT_BE_ZERO" ] }, "description": { "type": "string", "enum": [ "Payment amount cannot be zero. Please provide a valid amount." ] } } }, { "title": "INVALID_DECIMAL_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_DECIMAL_VALUE" ] }, "description": { "type": "string", "enum": [ "Payment amount value is invalid. Can have non-negative value with maximum 7 digits and upto 2 fractions." ] } } }, { "title": "INVALID_INTEGER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_VALUE" ] }, "description": { "type": "string", "enum": [ "Payment amount value is invalid. Can have non-negative value with maximum 6 digits." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Date should be of format yyyy-mm-dd." ] } } } ] } } } }, "invoices.payments-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE", "properties": { "issue": { "type": "string", "enum": [ "PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE" ] }, "description": { "type": "string", "enum": [ "Payment amount is greater than the amount due." ] } } }, { "title": "INVALID_INVOICE_TYPE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INVOICE_TYPE" ] }, "description": { "type": "string", "enum": [ "The invoice type is not valid for paying an invoice." ] } } }, { "title": "CANNOT_PROCESS_PAYMENTS", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_PROCESS_PAYMENTS" ] }, "description": { "type": "string", "enum": [ "Current invoice state does not support payment processing." ] } } } ] } } } }, "invoices.payments-delete-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "CANNOT_DELETE_EXTERNAL_PAYMENT", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_DELETE_EXTERNAL_PAYMENT" ] }, "description": { "type": "string", "enum": [ "The external payment cannot be deleted as the recorded refund cannot exceed the recored payment for an invoice." ] } } } ] } } } }, "invoices.refunds-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "Payment method is missing. Please provide a valid payment method." ] } } }, { "title": "INVALID_REFUND_METHOD", "properties": { "issue": { "type": "string", "enum": [ "INVALID_REFUND_METHOD" ] }, "description": { "type": "string", "enum": [ "The value provided is not an acceptable method of refund." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value provided is not an acceptable method of refund." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Currency code is not supported. Please provide a valid currency code." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "Amount value is missing. Please provide a valid amount." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Amount value is invalid. Should be a numeric value." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Amount value cannot be greater than the maximum limit of 32 characters length." ] } } }, { "title": "VALUE_CANNOT_BE_ZERO", "properties": { "issue": { "type": "string", "enum": [ "VALUE_CANNOT_BE_ZERO" ] }, "description": { "type": "string", "enum": [ "Refund amount cannot be zero." ] } } }, { "title": "INVALID_INTEGER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_VALUE" ] }, "description": { "type": "string", "enum": [ "Refund amount value is invalid. Can have non-negative value with maximum 6 digits." ] } } }, { "title": "INVALID_DECIMAL_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_DECIMAL_VALUE" ] }, "description": { "type": "string", "enum": [ "Refund amount value is invalid. Can have non-negative value with maximum 7 digits and upto 2 fractions." ] } } } ] } } } }, "invoices.refunds-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_REFUND_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_REFUND_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Recorded refunds cannot exceed recorded payments." ] } } }, { "title": "CANNOT_PROCESS_REFUNDS", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_PROCESS_REFUNDS" ] }, "description": { "type": "string", "enum": [ "Current invoice state does not support refunds." ] } } } ] } } } }, "invoices.remind-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "the value of a field is too long." ] } } }, { "title": "INVALID_ARRAY_MAX_ITEMS", "properties": { "issue": { "type": "string", "enum": [ "INVALID_ARRAY_MAX_ITEMS" ] }, "description": { "type": "string", "enum": [ "Only maximum of 100 email address is supported in additional recipients." ] } } } ] } } } }, "invoices.remind-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "CANNOT_REMIND_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_REMIND_INVOICE" ] }, "description": { "type": "string", "enum": [ "You cannot remind an invoice which is in DRAFT status. Only UNPAID, SENT and PARTIALLY_PAID invoices can be reminded." ] } } } ] } } } }, "invoices.search-invoices-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "Value exceeds max value." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "Value less than minimum value." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "the value of a field is too long." ] } } }, { "title": "INVALID_ARRAY_MAX_ITEMS", "properties": { "issue": { "type": "string", "enum": [ "INVALID_ARRAY_MAX_ITEMS" ] }, "description": { "type": "string", "enum": [ "the number of items in an array parameter is too large." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "the value of a field is either too short or too long." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "the value of a field is too long." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "the value of a field does not conform to the expected format." ] } } } ] } } } }, "invoices.update-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Address line2 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "National Number length should be between 1 and 14." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Address line1 length should be less than 300 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Country code is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Custom label length should be less than 50 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Given name length should be less than 140 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Language is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Admin area1 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item quantity length should be 1 and 14." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Surname length should be less than 140 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Attachment reference url length should be between 1 and 2000." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Country code length should be 2 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Business name length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Minimum due amount length should be less than 32 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Attachment id length should be between 1 and 255." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Admin area2 length should be less than 300 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Tax name length should be less than 100." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Website url length should be less than 2048 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Postal code length should be less than 60 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "National Number is not valid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Memo length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item name length should be less than 200 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "country code length should be between 1 and 3." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Template Id length should be less than 22 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Logo url length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice note length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Reference field length should be less than 120 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Due date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Terms and Conditions length should be less than 4000 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Email address length should be between 3 and 254." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Additional data length should be less than 4000." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Additional information value length should be less than 40 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Tax id length should be less than 100 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Invoice date is invalid." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Invoice number length should be less than 25 characters." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Item Date is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Item description length should be less than 1000 characters." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Shipping Tax name length should be less than 100 characters." ] } } } ] } } } }, "invoices.update-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_NOT_FOUND", "properties": { "issue": { "type": "string", "enum": [ "USER_NOT_FOUND" ] }, "description": { "type": "string", "enum": [ "User is not associated with paypal based on invoicer email." ] } } }, { "title": "AUTH_FLOW_REQUIRED", "properties": { "issue": { "type": "string", "enum": [ "AUTH_FLOW_REQUIRED" ] }, "description": { "type": "string", "enum": [ "User is required to pass auth challenge" ] } } } ] } } } }, "item": { "type": "object", "title": "Invoice Item", "description": "An array of invoice line item information. The maximum items for an invoice is `100`.", "properties": { "id": { "type": "string", "description": "The ID of the invoice line item.", "readOnly": true, "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 22 }, "name": { "type": "string", "description": "The item name for the invoice line item.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 200 }, "description": { "type": "string", "description": "The item description for the invoice line item.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 1000 }, "quantity": { "type": "string", "maxLength": 14, "minLength": 0, "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.", "pattern": "\\d+(.\\d{1,5})?$" }, "unit_amount": { "$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": { "$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": { "$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", "description": "Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total." }, "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.
", "$ref": "#/components/schemas/unit_of_measure" } }, "required": [ "name", "quantity", "unit_amount" ] }, "item_list": { "type": "array", "description": "An array of invoice line item information.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/item" } }, "language": { "type": "string", "description": "The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/).", "format": "ppaas_common_language_v3", "maxLength": 10, "minLength": 2, "pattern": "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$" }, "link_description": { "type": "object", "title": "Link Description", "description": "The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.", "required": [ "href", "rel" ], "properties": { "href": { "type": "string", "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call." }, "rel": { "type": "string", "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml)." }, "method": { "type": "string", "description": "The HTTP method required to make the related call.", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ] } } }, "link_description_list": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "items": { "$ref": "#/components/schemas/link_description" }, "minItems": 0, "maxItems": 2147483647 }, "metadata": { "type": "object", "title": "Metadata", "description": "The audit metadata. Captures all invoicing actions on create, send, update, and cancel.", "allOf": [ { "$ref": "#/components/schemas/template_metadata" }, { "properties": { "cancel_time": { "$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": { "type": "string", "description": "The actor who canceled the resource.", "readOnly": true }, "first_sent_time": { "$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": { "$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": { "type": "string", "description": "The email address of the account that last sent the resource.", "readOnly": true }, "created_by_flow": { "description": "The flow variation that created this invoice.", "$ref": "#/components/schemas/invoice_creation_flow", "readOnly": true }, "recipient_view_url": { "type": "string", "readOnly": true, "format": "uri", "description": "The URL for the invoice payer view hosted on paypal.com." }, "invoicer_view_url": { "type": "string", "readOnly": true, "format": "uri", "description": "The URL for the invoice merchant view hosted on paypal.com." } } } ] }, "money": { "type": "object", "title": "Money", "description": "The currency and amount for a financial transaction, such as a balance or payment due.", "properties": { "currency_code": { "$ref": "#/components/schemas/currency_code" }, "value": { "type": "string", "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/).", "maxLength": 32, "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" } }, "required": [ "currency_code", "value" ] }, "name": { "type": "object", "title": "Name", "description": "The name of the party.", "properties": { "prefix": { "type": "string", "description": "The prefix, or title, to the party's name.", "maxLength": 140 }, "given_name": { "type": "string", "description": "When the party is a person, the party's given, or first, name.", "maxLength": 140 }, "surname": { "type": "string", "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.", "maxLength": 140 }, "middle_name": { "type": "string", "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.", "maxLength": 140 }, "suffix": { "type": "string", "description": "The suffix for the party's name.", "maxLength": 140 }, "alternate_full_name": { "type": "string", "description": "DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.", "maxLength": 300 }, "full_name": { "type": "string", "description": "When the party is a person, the party's full name.", "maxLength": 300 } } }, "notification": { "type": "object", "title": "Notification", "description": "The email or SMS notification to send to the invoicer or payer on sending an invoice.", "properties": { "subject": { "type": "string", "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.
", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 4000 }, "note": { "type": "string", "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.
", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 4000 }, "send_to_invoicer": { "type": "boolean", "description": "Indicates whether to send a copy of the email to the merchant.", "default": false }, "send_to_recipient": { "type": "boolean", "description": "Indicates whether to send a copy of the email to the recipient.", "default": true }, "additional_recipients": { "$ref": "#/components/schemas/email_address_list" } } }, "partial_payment": { "type": "object", "title": "Partial Payment", "description": "The partial payment details. Includes the minimum amount that the invoicer expects from the payer.", "properties": { "allow_partial_payment": { "type": "boolean", "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`.
", "default": false }, "minimum_amount_due": { "$ref": "#/components/schemas/money", "description": "The minimum amount allowed for a partial payment. Valid only when `allow_partial_payment` is `true`." } } }, "payment_detail": { "type": "object", "title": "Payment Detail", "description": "The payment details of the invoice. Includes payment type, method, date, discount, and transaction type.", "properties": { "type": { "description": "The payment type in an invoicing flow which can be PayPal or an external cash or check payment.", "$ref": "#/components/schemas/payment_type", "readOnly": true }, "payment_id": { "type": "string", "description": "The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 22 }, "payment_date": { "$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": { "$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": { "description": "The payment mode or method through which the invoicer can accept the payment.", "$ref": "#/components/schemas/payment_method" }, "note": { "type": "string", "description": "A note associated with an external cash or check payment.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 2000 }, "amount": { "$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": { "$ref": "#/components/schemas/contact_name_address", "description": "The recipient's shipping information. Includes the user's contact information, which includes name and address." } }, "required": [ "method" ] }, "payment_detail_list": { "type": "array", "description": "An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/payment_detail" }, "readOnly": true }, "payment_method": { "type": "string", "title": "Payment Method", "description": "The payment mode or method through which the invoicer can accept the payments.", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "BANK_TRANSFER", "description": "Payments can be received through bank transfers." }, { "value": "CASH", "description": "Payments can be received as cash." }, { "value": "CHECK", "description": "Payments can be received as check." }, { "value": "CREDIT_CARD", "description": "Payments can be received through credit card payments." }, { "value": "DEBIT_CARD", "description": "Payments can be received through debit card payments." }, { "value": "PAYPAL", "description": "Payments can be received through paypal payments." }, { "value": "WIRE_TRANSFER", "description": "Payments can be received through wire transfer." }, { "value": "OTHER", "description": "Payments can be received through other modes." } ], "enum": [ "BANK_TRANSFER", "CASH", "CHECK", "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "WIRE_TRANSFER", "OTHER" ] }, "payment_reference": { "type": "object", "title": "Payment Reference", "description": "The reference to the payment detail.", "properties": { "payment_id": { "type": "string", "description": "The ID for the invoice payment.", "readOnly": true, "minLength": 1, "maxLength": 22, "pattern": "^[0-9A-Za-z_-]+$" } } }, "payment_term": { "type": "object", "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.", "properties": { "term_type": { "description": "The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.", "$ref": "#/components/schemas/payment_term_type" } } }, "payment_term_type": { "type": "string", "title": "Payment Term Type", "description": "The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "DUE_ON_RECEIPT", "description": "The payment for the invoice is due upon receipt of the invoice." }, { "value": "DUE_ON_DATE_SPECIFIED", "description": "The payment for the invoice is due on the date specified in the invoice." }, { "value": "NET_10", "description": "The payment for the invoice is due in 10 days." }, { "value": "NET_15", "description": "The payment for the invoice is due in 15 days." }, { "value": "NET_30", "description": "The payment for the invoice is due in 30 days." }, { "value": "NET_45", "description": "The payment for the invoice is due in 45 days." }, { "value": "NET_60", "description": "The payment for the invoice is due in 60 days." }, { "value": "NET_90", "description": "The payment for the invoice is due in 90 days." }, { "value": "NO_DUE_DATE", "description": "The invoice has no payment due date." } ], "enum": [ "DUE_ON_RECEIPT", "DUE_ON_DATE_SPECIFIED", "NET_10", "NET_15", "NET_30", "NET_45", "NET_60", "NET_90", "NO_DUE_DATE" ] }, "payment_type": { "type": "string", "title": "Payment Type", "description": "The payment type. Can be PayPal or an external payment. Includes cash or a check.", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "PAYPAL", "description": "The payment type is PayPal." }, { "value": "EXTERNAL", "description": "The payment type is an external cash or a check payment." } ], "enum": [ "PAYPAL", "EXTERNAL" ] }, "payments": { "type": "object", "title": "Payments", "description": "An array of payments registered against the invoice.", "properties": { "paid_amount": { "$ref": "#/components/schemas/money", "readOnly": true, "description": "The aggregated payment amounts against this invoice." }, "transactions": { "$ref": "#/components/schemas/payment_detail_list" } } }, "percentage": { "type": "string", "description": "The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`.", "format": "ppaas_common_percentage_v2", "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" }, "phone": { "type": "object", "title": "Phone", "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).", "properties": { "country_code": { "type": "string", "description": "The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "national_number": { "type": "string", "description": "The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" }, "extension_number": { "type": "string", "description": "The extension number.", "minLength": 1, "maxLength": 15, "pattern": "^[0-9]{1,15}?$" } }, "required": [ "country_code", "national_number" ] }, "phone_detail": { "type": "object", "title": "Phone Detail", "description": "The phone details. Includes the phone number and type.", "required": [ "phone_type" ], "allOf": [ { "$ref": "#/components/schemas/phone" }, { "properties": { "phone_type": { "$ref": "#/components/schemas/phone_type" } } } ] }, "phone_detail_list": { "type": "array", "items": { "$ref": "#/components/schemas/phone_detail" }, "description": "An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice." }, "phone_type": { "type": "string", "title": "Phone Type", "description": "The phone type.", "enum": [ "FAX", "HOME", "MOBILE", "OTHER", "PAGER" ] }, "qr_config": { "type": "object", "title": "QR Configuration", "description": "The configuration for a QR code.", "properties": { "width": { "type": "integer", "description": "The width, in pixels, of the QR code image. Value is from `150` to `500`.", "default": 500, "minimum": 150, "maximum": 500 }, "height": { "type": "integer", "description": "The height, in pixels, of the QR code image. Value is from `150` to `500`.", "default": 500, "minimum": 150, "maximum": 500 }, "action": { "type": "string", "description": "The type of URL for which to generate a QR code. Valid values are `pay` and `details`.", "default": "pay", "pattern": "^(pay|details)$", "minLength": 0, "maxLength": 7 } } }, "recipient_info": { "type": "object", "title": "Recipient Information", "description": "The billing and shipping information. Includes name, email, address, phone, and language.", "properties": { "billing_info": { "$ref": "#/components/schemas/billing_info", "description": "The billing information for the invoice recipient. Includes name, address, email, phone, and language." }, "shipping_info": { "$ref": "#/components/schemas/contact_name_address", "description": "The recipient's shipping information. Includes the user's contact information, which includes name and address." } } }, "recipient_info_list": { "type": "array", "items": { "$ref": "#/components/schemas/recipient_info" }, "minItems": 0, "maxItems": 100, "description": "The billing and shipping information. Includes name, email, address, phone and language." }, "refund_detail": { "type": "object", "title": "Refund Detail", "description": "The refund details of the invoice. Includes the refund type, date, amount, and method.", "properties": { "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.", "$ref": "#/components/schemas/payment_type", "readOnly": true }, "refund_id": { "type": "string", "description": "The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.", "pattern": "^[\\S\\s]*$", "minLength": 0, "maxLength": 22, "readOnly": true }, "refund_date": { "$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": { "$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": { "description": "The payment mode or method through which the invoicer can accept the payments.", "$ref": "#/components/schemas/payment_method" } }, "required": [ "method" ] }, "refund_detail_list": { "type": "array", "description": "An array of refund details for the invoice. Includes the refund type, date, amount, and method.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/refund_detail" }, "readOnly": true }, "refund_reference": { "type": "object", "title": "Refund Payment Reference", "description": "The reference to the refund payment detail.", "properties": { "refund_id": { "type": "string", "description": "The ID of the refund of an invoice payment.", "readOnly": true, "minLength": 1, "maxLength": 22, "pattern": "^[0-9A-Za-z_-]+$" } } }, "refunds": { "type": "object", "title": "Refunds", "description": "The invoicing refund details. Includes the refund type, date, amount, and method.", "properties": { "refund_amount": { "$ref": "#/components/schemas/money", "readOnly": true, "description": "The aggregated refund amounts." }, "transactions": { "$ref": "#/components/schemas/refund_detail_list" } } }, "restrictive_email_address": { "type": "string", "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.
", "minLength": 3, "maxLength": 254, "pattern": "^(?!\\.)(?:[A-Za-z0-9!#$&'*\\/=?^`{|}~_%+-]|\\.(?!\\.)){1,64}(?
  • true. Response lists only merchant-archived invoices.
  • false. Response lists only unarchived invoices.
  • null. Response lists all invoices.
    • " }, "fields": { "$ref": "#/components/schemas/fields_list" } } }, "shipping_cost": { "type": "object", "title": "Shipping Cost", "description": "The shipping fee for all items. Includes tax on shipping.", "properties": { "amount": { "$ref": "#/components/schemas/money", "description": "The shipping amount. Value is from `0` to `1000000`. Supports up to two decimal places." }, "tax": { "$ref": "#/components/schemas/tax", "description": "The tax associated with the shipping." } } }, "tax": { "type": "object", "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.", "properties": { "name": { "type": "string", "description": "The name of the tax applied on the invoice items.", "maxLength": 100, "minLength": 0, "pattern": "^[\\s\\S]*$" }, "percent": { "$ref": "#/components/schemas/percentage", "description": "The tax rate. Value is from `0` to `100`. Supports up to five decimal places." }, "amount": { "$ref": "#/components/schemas/money", "description": "The calculated tax amount. The tax amount is added to the item total.", "readOnly": true }, "tax_note": { "type": "string", "description": "The tax note used to track the tax related data.", "maxLength": 40, "minLength": 0, "pattern": "^[\\s\\S]*$" } }, "required": [ "name", "percent" ] }, "template": { "type": "object", "title": "Template", "description": "The template with invoice details to load with all captured fields.", "properties": { "id": { "type": "string", "description": "The ID of the template.", "readOnly": true, "maxLength": 30, "minLength": 0, "pattern": "^[\\S\\s]*$" }, "name": { "type": "string", "description": "The template name.
    Note: The template name must be unique.
    ", "maxLength": 500, "minLength": 1, "pattern": "^[\\S\\s]*$" }, "default_template": { "type": "boolean", "description": "Indicates whether this template is the default template. A invoicer can have one default template." }, "template_info": { "$ref": "#/components/schemas/template_info", "description": "The template details. Includes invoicer business information, invoice recipients, items, and configuration." }, "settings": { "description": "The template settings. Describes which fields to show or hide when you create an invoice.", "$ref": "#/components/schemas/template_settings" }, "unit_of_measure": { "$ref": "#/components/schemas/unit_of_measure", "description": "The unit of measure for the template. Value is quantity, hours, or amount." }, "standard_template": { "type": "boolean", "description": "Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.", "readOnly": true }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "template_configuration": { "type": "object", "title": "Template Configuration", "description": "The template configuration details. Includes tax information, tip, and partial payment.", "properties": { "tax_calculated_after_discount": { "type": "boolean", "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.", "default": true }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether the unit price includes tax.", "default": false }, "allow_tip": { "type": "boolean", "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`.
    ", "default": false }, "partial_payment": { "$ref": "#/components/schemas/partial_payment", "description": "The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay." }, "has_conditional_rule": { "type": "boolean", "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.", "default": false } } }, "template_detail": { "type": "object", "title": "Template Detail", "description": "The template-related details. Includes notes, terms and conditions, memo, and attachments.", "allOf": [ { "$ref": "#/components/schemas/detail" }, { "properties": { "payment_term": { "$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", "description": "The audit metadata. Captures all template actions on create and update." } } } ] }, "template_display_preference": { "type": "object", "title": "Template Display Preference", "description": "The template display preference.", "properties": { "hidden": { "type": "boolean", "description": "Indicates whether to show or hide this field.", "default": false } } }, "template_info": { "type": "object", "title": "Template Information", "description": "The template details. Includes invoicer business information, invoice recipients, items, and configuration.", "properties": { "detail": { "$ref": "#/components/schemas/template_detail", "description": "The template-related details. Includes notes, terms and conditions, memo, and attachments." }, "invoicer": { "$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": { "$ref": "#/components/schemas/definitions-recipient_info_list" }, "additional_recipients": { "$ref": "#/components/schemas/email_address_list" }, "items": { "$ref": "#/components/schemas/definitions-item_list" }, "configuration": { "$ref": "#/components/schemas/template_configuration", "description": "The template configuration details. Includes tax information, tip, and partial payment." }, "amount": { "$ref": "#/components/schemas/amount_summary_detail", "description": "The invoice amount summary of the item total, discount, tax total, and shipping." }, "due_amount": { "$ref": "#/components/schemas/money", "description": "The amount due for the invoice.", "readOnly": true } } }, "template_item_field": { "type": "string", "title": "Template Item Field", "description": "The field names for the invoice line items in the template.", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "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." }, { "value": "ITEMS_DESCRIPTION", "description": "The description of the item in the invoice template." }, { "value": "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*." }, { "value": "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." }, { "value": "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." } ], "enum": [ "ITEMS_QUANTITY", "ITEMS_DESCRIPTION", "ITEMS_DATE", "ITEMS_DISCOUNT", "ITEMS_TAX" ] }, "template_item_setting": { "type": "object", "title": "Template Item Setting", "description": "The template item setting. Sets a template as the default template or edit template.", "properties": { "field_name": { "description": "The field name in `template_data` for which to map corresponding display preferences.", "$ref": "#/components/schemas/template_item_field" }, "display_preference": { "description": "The display preference.", "$ref": "#/components/schemas/template_display_preference" } } }, "template_item_setting_list": { "type": "array", "minItems": 0, "maxItems": 2147483647, "description": "The template item headers display preference.", "items": { "$ref": "#/components/schemas/template_item_setting" } }, "template_list": { "type": "array", "description": "An array of details for each template. If `fields` is `none`, returns only the template name, ID, and default status.", "items": { "$ref": "#/components/schemas/template" }, "minItems": 0, "maxItems": 2147483647 }, "template_metadata": { "type": "object", "title": "Template Metadata", "description": "The audit metadata. Captures all template actions on create and update.", "properties": { "create_time": { "$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": { "type": "string", "description": "The email address of the account that created the resource.", "readOnly": true, "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "last_update_time": { "$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": { "type": "string", "description": "The email address of the account that last edited the resource.", "readOnly": true, "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" } } }, "template_settings": { "type": "object", "title": "Template Settings", "description": "The template settings. Sets a template as the default template or edit template.", "properties": { "template_item_settings": { "$ref": "#/components/schemas/template_item_setting_list" }, "template_subtotal_settings": { "$ref": "#/components/schemas/template_subtotal_setting_list" } } }, "template_subtotal_field": { "type": "string", "title": "Template Subtotal Field", "description": "The field names in the template for discount, shipping, and custom amounts.", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "DISCOUNT", "description": "The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total." }, { "value": "SHIPPING", "description": "The shipping fee for all items in the invoice template. Also includes the tax on shipping." }, { "value": "CUSTOM", "description": "The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount." } ], "enum": [ "DISCOUNT", "SHIPPING", "CUSTOM" ] }, "template_subtotal_setting": { "type": "object", "title": "Template Subtotal Setting", "description": "The template subtotal setting. Includes the field name and display preference.", "properties": { "field_name": { "description": "The field name in `template_data` for which to map corresponding display preferences.", "$ref": "#/components/schemas/template_subtotal_field" }, "display_preference": { "description": "The display preference.", "$ref": "#/components/schemas/template_display_preference" } } }, "template_subtotal_setting_list": { "type": "array", "minItems": 0, "maxItems": 2147483647, "description": "The template subtotal headers display preference.", "items": { "$ref": "#/components/schemas/template_subtotal_setting" } }, "templates": { "type": "object", "title": "Templates", "minItems": 1, "description": "An array of merchant-created templates with associated details that include the emails, addresses, and phone numbers from the user's PayPal profile.", "properties": { "addresses": { "$ref": "#/components/schemas/address_portable_list" }, "emails": { "description": "An array of emails in the user's PayPal profile.", "$ref": "#/components/schemas/email_address", "readOnly": true }, "phones": { "$ref": "#/components/schemas/templates_definitions-phone_detail_list" }, "templates": { "$ref": "#/components/schemas/template_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "templates.create-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "TEMPLATE_NAME_ALREADY_EXISTS", "properties": { "issue": { "type": "string", "enum": [ "TEMPLATE_NAME_ALREADY_EXISTS" ] }, "description": { "type": "string", "enum": [ "Template name already exists." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Template name length should be between 1 and 500." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "the value of a field is either too short or too long." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Value of the field is too long." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "the value of a field does not conform to the expected format." ] } } } ] } } } }, "templates.create-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "CANNOT_CANCEL_DRAFT_INVOICE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_CANCEL_DRAFT_INVOICE" ] }, "description": { "type": "string", "enum": [ "Cannot cancel a draft invoice." ] } } } ] } } } }, "templates.delete-403": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "PERMISSION_DENIED", "properties": { "issue": { "type": "string", "enum": [ "PERMISSION_DENIED" ] }, "description": { "type": "string", "enum": [ "The requested template is not associated with the requested user." ] } } }, { "title": "CANNOT_DELETE_GLOBAL_TEMPLATE", "properties": { "issue": { "type": "string", "enum": [ "CANNOT_DELETE_GLOBAL_TEMPLATE" ] }, "description": { "type": "string", "enum": [ "Global templates cannot be deleted." ] } } } ] } } } }, "templates.get-403": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "PERMISSION_DENIED", "properties": { "issue": { "type": "string", "enum": [ "PERMISSION_DENIED" ] }, "description": { "type": "string", "enum": [ "The requested template is not associated with the requested user." ] } } } ] } } } }, "templates.update-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "TEMPLATE_NAME_ALREADY_EXISTS", "properties": { "issue": { "type": "string", "enum": [ "TEMPLATE_NAME_ALREADY_EXISTS" ] }, "description": { "type": "string", "enum": [ "Template name already exists." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Template name length should be between 1 and 500." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Currency code length should be 3 characters." ] } } }, { "title": "INVALID_STRING_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_LENGTH" ] }, "description": { "type": "string", "enum": [ "Value of the field is either too short or too long." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "Value of the field is too long." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "Value of the field does not conform to the expected format." ] } } } ] } } } }, "templates_definitions-phone_detail_list": { "type": "array", "description": "An array of phone numbers in the user's PayPal profile.", "items": { "$ref": "#/components/schemas/phone_detail" }, "minItems": 0, "maxItems": 2147483647 }, "unit_of_measure": { "type": "string", "description": "The unit of measure for the invoiced item.", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "x-enumDescriptions": [ { "value": "QUANTITY", "description": "The unit of measure is quantity. This invoice template is typically used for physical goods." }, { "value": "HOURS", "description": "The unit of measure is hours. This invoice template is typically used for services." }, { "value": "AMOUNT", "description": "The unit of measure is amount. This invoice template is typically used when only amount is required." } ], "enum": [ "QUANTITY", "HOURS", "AMOUNT" ] } }, "parameters": { "page": { "name": "page", "in": "query", "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.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, "page_size": { "name": "page_size", "in": "query", "description": "The maximum number of templates to return in the response.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "total_required": { "name": "total_required", "in": "query", "description": "Indicates whether the to show total_pages and total_items in the response.", "schema": { "type": "boolean", "default": false } }, "fields": { "name": "fields", "in": "query", "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`.", "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^(all|none)$", "default": "all" } }, "invoice_id": { "name": "invoice_id", "in": "path", "required": true, "description": "The ID of the draft invoice to delete.", "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^.*$" } }, "transaction_id": { "name": "transaction_id", "in": "path", "required": true, "description": "The ID of the external refund transaction to delete.", "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^.*$" } }, "send_to_recipient": { "name": "send_to_recipient", "in": "query", "description": "Indicates whether to send the invoice update notification to the recipient.", "schema": { "type": "boolean", "default": true } }, "send_to_invoicer": { "name": "send_to_invoicer", "in": "query", "description": "Indicates whether to send the invoice update notification to the merchant.", "schema": { "type": "boolean", "default": true } }, "template_id": { "name": "template_id", "in": "path", "required": true, "description": "The ID of the template to delete.", "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^.*$" } }, "id": { "name": "id", "description": "The invoice id of the account.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[0-9]+$" } } }, "examples": { "qr_config": { "value": { "width": 400, "height": 400 } } } } }