openapi: 3.0.3 info: title: Paypal Subscriptions Authorizations Invoices API description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see Subscriptions Overview. version: '1.6' 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. paths: /v2/invoicing/invoices: post: summary: Paypal 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' examples: '0': $ref: '#/components/examples/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' default: $ref: '#/components/responses/default' requestBody: content: application/json: schema: $ref: '#/components/schemas/invoice' examples: '0': $ref: '#/components/examples/invoice_draft' 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: Paypal 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' 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: Paypal 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: A successful request returns the HTTP `202 Accepted` status code with no JSON response body, when the invoice issue date is in future. content: application/json: schema: $ref: '#/components/schemas/202-response' multipart/mixed: schema: $ref: '#/components/schemas/202-response' '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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/notification' examples: '0': $ref: '#/components/examples/notification_invoice' 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: Paypal 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. 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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/notification' examples: '0': $ref: '#/components/examples/notification_reminder' 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: Paypal 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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/notification' examples: '0': $ref: '#/components/examples/notification_invoice_cancel' 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: Paypal 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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/payment_detail' examples: '0': $ref: '#/components/examples/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: Paypal 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. '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' 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: Paypal 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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/refund_detail' examples: '0': $ref: '#/components/examples/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: Paypal 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. '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' 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: Paypal 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' 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: Paypal 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 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' '403': description: Authorization Error. content: application/json: schema: $ref: '#/components/schemas/error_403' default: $ref: '#/components/responses/default' security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite tags: - Invoices /v2/invoicing/invoices/{invoice_id}: get: summary: Paypal 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' '422': description: Unprocessable Entity. content: application/json: schema: $ref: '#/components/schemas/error_422' 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: Paypal 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. 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/422' multipart/mixed: schema: allOf: - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/422' 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: Paypal 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' default: $ref: '#/components/responses/default' parameters: - $ref: '#/components/parameters/invoice_id' security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/readwrite tags: - Invoices components: parameters: 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 transaction_id: name: transaction_id in: path required: true description: The ID of the external refund transaction to delete. schema: type: string 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 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 pattern: (?i)^(all|none)$ default: all 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 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 invoice_id: name: invoice_id in: path required: true description: The ID of the draft invoice to delete. schema: type: string 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 schemas: 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' link_description: type: object title: Link Description description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information. required: - href - rel properties: href: type: string description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. rel: type: string description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH error_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' 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. 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' 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 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 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: type: array items: $ref: '#/components/schemas/recipient_info' maxItems: 100 description: The billing and shipping information. Includes name, email, address, phone and language. additional_recipients: type: array 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' items: type: array description: An array of invoice line item information. maxItems: 100 items: $ref: '#/components/schemas/item' 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: 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' 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: type: array description: An array of refund details for the invoice. Includes the refund type, date, amount, and method. maxItems: 100 items: $ref: '#/components/schemas/refund_detail' readOnly: true 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: 7 pattern: ^[A-Z]*$ enum: - CONNECT - DELETE - GET - HEAD - OPTIONS - PATCH - POST - PUT 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 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*. 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/). 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. 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 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 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_500' - $ref: '#/components/schemas/error_503' 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 post office (PO) number. 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. 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. maxLength: 4000 memo: type: string description: A private bookkeeping memo for the user. maxLength: 500 attachments: type: array description: An array of PayPal IDs for the files that are attached to an invoice. maximum: 5 items: $ref: '#/components/schemas/file_reference' 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 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. payment_type: type: string title: Payment Type description: The payment type. Can be PayPal or an external payment. Includes cash or a check. enum: - PAYPAL - EXTERNAL 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' 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: ^.+@[^"\-].+$ 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})$ 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 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. 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 language: type: string description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/). format: ppaas_common_language_v3 maxLength: 10 minLength: 2 pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$ 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.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. 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' 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. 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 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. 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: 127 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 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`. 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. 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. 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: (?i)^(pay|details)$ maxLength: 7 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. payment_method: type: string title: Payment Method description: The payment mode or method through which the invoicer can accept the payments. enum: - BANK_TRANSFER - CASH - CHECK - CREDIT_CARD - DEBIT_CARD - PAYPAL - WIRE_TRANSFER - OTHER country_code: type: string description: The [two-character ISO 3166-1 code](/docs/integration/direct/rest/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)$ 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/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: 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. 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 unit_of_measure: type: string description: The unit of measure for the invoiced item. enum: - QUANTITY - HOURS - AMOUNT 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 '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. 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]+$ 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' phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER 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. enum: - DUE_ON_RECEIPT - DUE_ON_DATE_SPECIFIED - NET_10 - NET_15 - NET_30 - NET_45 - NET_60 - NET_90 - NO_DUE_DATE 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: type: string description: The location of the field that caused the error. Value is `body`, `path`, or `query`. default: body issue: type: string description: The unique, fine-grained application-level error code. description: type: string description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value. required: - issue 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. 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. 202-response: type: object title: Accepted Response description: The HTTP `202 Accepted` response. properties: links: 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' readOnly: true 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. 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. 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*. 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. 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 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 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. currency_code: description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 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. 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/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: type: array items: $ref: '#/components/schemas/phone_detail' description: The invoice recipient's phone numbers. Extension number is not supported. 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. 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. 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 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: 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. maxItems: 100 items: $ref: '#/components/schemas/payment_detail' readOnly: true 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' invoice_creation_flow: type: string title: Invoice Creation Flow description: The frequency at which the invoice is sent: enum: - MULTIPLE_RECIPIENTS_GROUP - BATCH - REGULAR_SINGLE '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. 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 maxLength: 22 name: type: string description: The item name for the invoice line item. maxLength: 200 description: type: string description: The item description for the invoice line item. 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. 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 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])$ 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. invoice_status: type: string title: Invoice Status description: The status of the invoice. enum: - DRAFT - SENT - SCHEDULED - PAID - MARKED_AS_PAID - CANCELLED - REFUNDED - PARTIALLY_PAID - PARTIALLY_REFUNDED - MARKED_AS_REFUNDED - UNPAID - PAYMENT_PENDING 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. 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. maxLength: 4000 note: type: string description: A note to the payer. 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: type: array 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.
' maxItems: 100 items: $ref: '#/components/schemas/email_address' 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. default: PayPal system template maxLength: 30 '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. 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. 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](/docs/integration/direct/rest/currency-codes/). maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ required: - currency_code - value 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: 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-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment. maxLength: 100 required: - country_code 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' 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. 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 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 required: - name - percent 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. maxLength: 25 readOnly: true 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' 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]+))$ 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 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 items: type: array description: The list of invoices that match the search criteria. readOnly: true items: $ref: '#/components/schemas/invoice' links: 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' 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. maxLength: 50 amount: $ref: '#/components/schemas/money' description: The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places. responses: default: description: The default response. content: application/json: schema: $ref: '#/components/schemas/error_default' examples: notification_invoice: value: send_to_invoicer: true qr_config: value: width: 400 height: 400 invoice: value: detail: invoice_number: '#123' reference: deal-ref invoice_date: '2018-11-12' currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: '2018-11-22' invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US email_address: merchant@example.com phones: - country_code: '001' national_number: '4085551234' phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US email_address: bill-me@example.com phones: - country_code: '001' national_number: '4884551234' phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: '1' unit_amount: currency_code: USD value: '50.00' tax: name: Sales Tax percent: '7.25' discount: percent: '5' unit_of_measure: QUANTITY - name: Yoga t-shirt quantity: '1' unit_amount: currency_code: USD value: '10.00' tax: name: Sales Tax percent: '7.25' discount: amount: currency_code: USD value: '5.00' unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: '20.00' allow_tip: true tax_calculated_after_discount: true tax_inclusive: false template_id: TEMP-19V05281TU309413B amount: breakdown: custom: label: Packing Charges amount: currency_code: USD value: '10.00' shipping: amount: currency_code: USD value: '10.00' tax: name: Sales Tax percent: '7.25' discount: invoice_discount: percent: '5' payment_detail: value: method: BANK_TRANSFER payment_date: '2018-05-01' amount: currency_code: USD value: '10.00' refund_detail: value: method: BANK_TRANSFER refund_date: '2018-05-21' amount: currency_code: USD value: '5.00' notification_reminder: value: subject: 'Reminder: Payment due for the invoice #ABC-123' note: Please pay before the due date to avoid incurring late payment charges which will be adjusted in the next bill generated. send_to_invoicer: true additional_recipients: - customer-a@example.com - customer@example.com notification_invoice_cancel: value: subject: Invoice Cancelled note: Cancelling the invoice send_to_invoicer: true send_to_recipient: true additional_recipients: - user@example.com invoice_draft: value: id: INV2-C82X-JNN9-Y6S5-CNXW status: DRAFT detail: invoice_number: '#123' reference: deal-refernce-update invoice_date: '2018-11-12' currency_code: USD note: Thank you for your business. term: No refunds after 30 days. memo: This is a long contract payment_term: term_type: NET_10 due_date: '2018-11-22' invoicer: name: given_name: David surname: Larusso address: address_line_1: 1234 First Street address_line_2: 337673 Hillside Court admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US email_address: merchant@example.com phones: - country_code: '001' national_number: '4085551234' phone_type: MOBILE website: www.test.com tax_id: ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g logo_url: https://example.com/logo.PNG additional_notes: 2-4 primary_recipients: - billing_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US email_address: bill-me@example.com phones: - country_code: '001' national_number: '4884551234' phone_type: HOME additional_info_value: add-info shipping_info: name: given_name: Stephanie surname: Meyers address: address_line_1: 1234 Main Street admin_area_2: Anytown admin_area_1: CA postal_code: '98765' country_code: US items: - name: Yoga Mat description: Elastic mat to practice yoga. quantity: '1' unit_amount: currency_code: USD value: '50.00' tax: name: Sales Tax percent: '7.25' amount: currency_code: USD value: '3.27' discount: percent: '5' amount: currency_code: USD value: '2.5' unit_of_measure: QUANTITY - name: Yoga t-shirt quantity: '1' unit_amount: currency_code: USD value: '10.00' tax: name: Sales Tax percent: '7.25' amount: currency_code: USD value: '0.34' discount: amount: currency_code: USD value: '5.00' unit_of_measure: QUANTITY configuration: partial_payment: allow_partial_payment: true minimum_amount_due: currency_code: USD value: '20.00' allow_tip: true tax_calculated_after_discount: true tax_inclusive: false template_id: TEMP-19V05281TU309413B amount: currency_code: USD value: '74.21' breakdown: item_total: currency_code: USD value: '60.00' custom: label: Packing Charges amount: currency_code: USD value: '10.00' shipping: amount: currency_code: USD value: '10.00' tax: name: Sales Tax percent: '7.25' amount: currency_code: USD value: '0.73' discount: item_discount: currency_code: USD value: '-7.50' invoice_discount: percent: '5' amount: currency_code: USD value: '-2.63' tax_total: currency_code: USD value: '4.34' securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token scopes: https://uri.paypal.com/services/subscriptions: Manage plan & subscription externalDocs: url: https://developer.paypal.com/docs/api/subscriptions/v1/