{ "openapi": "3.0.3", "info": { "title": "Invoicing", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see Invoicing Overview and the Invoicing Integration Guide.", "version": "1.13", "contact": {} }, "x-hidden": true, "paths": { "/v1/invoicing/invoices": { "post": { "summary": "Create draft invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
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": "invoice.create", "responses": { "201": { "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows invoice details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "requestBody": { "$ref": "#/components/requestBodies/invoice" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] }, "get": { "summary": "List invoices", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.", "operationId": "invoice.get_all", "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" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/total_count_required" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/search": { "post": { "summary": "Search for invoices", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Searches for invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.", "operationId": "invoice.search", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the invoices that match the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoices" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search" } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "search" ] } }, "/v1/invoicing/invoices/{invoice_id}/send": { "post": { "summary": "Send invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Sends an invoice, by ID, to a customer. To suppress the merchant's email notification, set the `notify_merchant` query parameter to `false`.
Note: After you send an invoice, you cannot resend it.
", "operationId": "invoice.send", "responses": { "202": { "description": "A successful request returns the HTTP `202 Accepted` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/notify_merchant" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/schedule": { "post": { "summary": "Schedule invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Schedules an invoice, by ID, to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to SENT.
Note: To change the scheduled date, adjust the invoice date and update invoice. To send the invoice immediately, update the invoice date to today or to a date in the past.
", "operationId": "invoice.schedule", "responses": { "202": { "description": "A successful request returns the HTTP `202 Accepted` status code and a JSON response body with a link to the invoice ." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/remind": { "post": { "summary": "Send invoice reminder", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
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": "invoice.remind", "responses": { "202": { "description": "A successful request returns the HTTP `202 Accepted` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification" } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/cancel": { "post": { "summary": "Cancel sent invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.", "operationId": "invoice.cancel", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel-notification" } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/record-payment": { "post": { "summary": "Mark invoice as paid", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Marks the status of an invoice, by ID, as paid.", "operationId": "invoice.record-payment", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment-detail" } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/record-refund": { "post": { "summary": "Mark invoice as refunded", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Marks the status of an invoice, by ID, as refunded.", "operationId": "invoice.record-refund", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-detail" } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}": { "get": { "summary": "Show invoice details", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Shows details for an invoice, by ID.", "operationId": "invoice.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" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] }, "put": { "summary": "Update invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Fully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates.", "operationId": "invoice.update", "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" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/notify_merchant" } ], "requestBody": { "$ref": "#/components/requestBodies/invoice" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] }, "delete": { "summary": "Delete draft invoice", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes invoices in the DRAFT or SCHEDULED state, by ID. 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": "invoice.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/payment-records/{transaction_id}": { "delete": { "summary": "Delete external payment", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes an external payment, by invoice ID and transaction ID.", "operationId": "invoice.delete_external_payment", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/transaction_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/refund-records/{transaction_id}": { "delete": { "summary": "Delete external refund", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Deletes an external refund, by invoice ID and transaction ID.", "operationId": "invoice.delete_external_refund", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/transaction_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/{invoice_id}/qr-code": { "get": { "summary": "Generate QR code", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
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": "invoice.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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qr_code" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/invoice_id" }, { "$ref": "#/components/parameters/width" }, { "$ref": "#/components/parameters/height" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/invoices/next-invoice-number": { "post": { "summary": "Generate invoice number", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
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": "invoice.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" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "invoices" ] } }, "/v1/invoicing/templates": { "post": { "summary": "Create template", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.
", "operationId": "template.create", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "requestBody": { "$ref": "#/components/requestBodies/template" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "templates" ] }, "get": { "summary": "List templates", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Lists merchant-created templates with associated details. The associated details include the email addresses, postal addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template.", "operationId": "template.get_templates", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/templates" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/fields" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "templates" ] } }, "/v1/invoicing/templates/{template_id}": { "get": { "summary": "Show template details", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Shows details for a template, by ID.", "operationId": "template.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "templates" ] }, "delete": { "summary": "Delete template", "description": "Deletes a template, by ID.", "operationId": "template.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "templates" ] }, "put": { "summary": "Update template", "description": "
Deprecation notice: The /v1/invoices endpoint is deprecated. Use the /v2/invoices endpoint instead. For details, see PayPal Invoicing Basic Integration.
Updates a template, by ID. In the JSON request body, specify a complete `template` object. The update method does not support partial updates.", "operationId": "template.update", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/template_id" } ], "requestBody": { "$ref": "#/components/requestBodies/template" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/invoicing" ] } ], "tags": [ "templates" ] } } }, "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 mark invoices as fully or partially paid, or as refunded. Lastly, you can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone." }, { "name": "templates", "description": "Use the `/templates` resource to create, list, show details for, update, and delete invoice templates. The template API is useful when creating a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.
Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. Then, use the URI of that logo when you create an invoice.
" }, { "name": "files", "description": "Use the `/files` resource to upload a file attachment for an invoice." }, { "name": "group-invoices", "description": "Use the `/group-invoices` resource to create a batch, or group of, invoices." }, { "name": "search", "description": "Use the `/search` resource to search for invoices." }, { "name": "summaries", "description": "Use the `/summaries` resource to list invoice summary information, including counts. The list is grouped by invoice status." } ], "externalDocs": { "url": "https://developer.paypal.com/docs/api/invoicing/v1/" }, "servers": [ { "url": "https://api-m.sandbox.paypal.com", "description": "PayPal Sandbox Environment" }, { "url": "https://api-m.paypal.com", "description": "PayPal Live Environment" } ], "components": { "requestBodies": { "invoice": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" } } } }, "template": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } }, "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/v1/oauth2/token", "scopes": { "https://uri.paypal.com/services/invoicing": "Manage invoice resource." } } } } }, "parameters": { "page": { "name": "page", "in": "query", "description": "The *zero-relative* start index of the entire list of merchant invoices that are returned in the response. So, the combination of `page=0` and `page_size=20` returns the first 20 invoices. The combination of `page=20` and `page_size=20` returns the next 20 invoices.", "schema": { "type": "integer", "default": 1 } }, "page_size": { "name": "page_size", "in": "query", "description": "The number of invoices to return in the response.", "schema": { "type": "integer", "default": 20 } }, "total_count_required": { "name": "total_count_required", "in": "query", "description": "Indicates whether to show the total count in the response.", "schema": { "type": "boolean", "default": false } }, "invoice_id": { "name": "invoice_id", "in": "path", "description": "The ID of the invoice for which to generate a QR code.", "required": true, "schema": { "type": "string" } }, "notify_merchant": { "name": "notify_merchant", "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", "description": "The ID of the external refund transaction to delete.", "required": true, "schema": { "type": "string" } }, "width": { "name": "width", "in": "query", "description": "The width, in pixels, of the QR code image. Value is from `150` to `500`.", "schema": { "type": "integer", "default": 500 } }, "height": { "name": "height", "in": "query", "description": "The height, in pixels, of the QR code image. Value is from `150` to `500`.", "schema": { "type": "integer", "default": 500 } }, "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", "default": "all" } }, "template_id": { "name": "template_id", "in": "path", "description": "The ID of the template to update.", "required": true, "schema": { "type": "string" } } }, "schemas": { "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" ] }, "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" } ] }, "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" ] } } }, "error_400": { "type": "object", "title": "Bad Request Error", "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "properties": { "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_401": { "type": "object", "title": "Unauthorized Error", "description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "properties": { "name": { "type": "string", "enum": [ "AUTHENTICATION_FAILURE" ] }, "message": { "type": "string", "enum": [ "Authentication failed due to missing authorization header, or invalid authentication credentials." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_403": { "type": "object", "title": "Not Authorized Error", "description": "The client is not authorized to access this resource, although it may have valid credentials. ", "properties": { "name": { "type": "string", "enum": [ "NOT_AUTHORIZED" ] }, "message": { "type": "string", "enum": [ "Authorization failed due to insufficient permissions." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_404": { "type": "object", "title": "Not found Error", "description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "The specified resource does not exist." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_409": { "type": "object", "title": "Resource Conflict Error", "description": "The server has detected a conflict while processing this request.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_CONFLICT" ] }, "message": { "type": "string", "enum": [ "The server has detected a conflict while processing this request." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_415": { "type": "object", "title": "Unsupported Media Type Error", "description": "The server does not support the request payload's media type.", "properties": { "name": { "type": "string", "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] }, "message": { "type": "string", "enum": [ "The server does not support the request payload's media type." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_422": { "type": "object", "title": "Unprocessable Entity Error", "description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "error_details-2": { "type": "object", "title": "Error Details", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "The name of the field that caused the error." }, "issue": { "type": "string", "description": "The reason for the error." } }, "required": [ "field", "issue" ] }, "error": { "type": "object", "title": "Error", "description": "The error information.", "properties": { "name": { "type": "string", "description": "The human-readable, unique name of the error.", "readOnly": true }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes.", "readOnly": true }, "message": { "type": "string", "description": "The message that describes the error.", "readOnly": true }, "information_link": { "type": "string", "description": "The URI to detailed information related to this error for the developer.", "readOnly": true }, "details": { "type": "array", "description": "An array of additional details for the error.", "readOnly": true, "items": { "$ref": "#/components/schemas/error_details-2" } } }, "required": [ "name", "message", "information_link" ] }, "address": { "type": "object", "title": "Address", "description": "The address, which is either a billing address or shipping address in a payment.", "properties": { "line1": { "type": "string", "description": "The first line of the address. For example, number or street." }, "line2": { "type": "string", "description": "The second line of the address. For example, suite or apartment number." }, "city": { "type": "string", "description": "The city name." }, "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 is used in that country's top-level domain names. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
" }, "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)." }, "state": { "type": "string", "description": "The [code](/docs/integration/direct/rest/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/integration/direct/rest/state-codes/#argentina), [Brazil](/docs/integration/direct/rest/state-codes/#brazil), [Canada](/docs/integration/direct/rest/state-codes/#canada), [China](/docs/integration/direct/rest/state-codes/#china), [India](/docs/integration/direct/rest/state-codes/#india), [Italy](/docs/integration/direct/rest/state-codes/#italy), [Japan](/docs/integration/direct/rest/state-codes/#japan), [Mexico](/docs/integration/direct/rest/state-codes/#mexico), [Thailand](/docs/integration/direct/rest/state-codes/#thailand), or [United States](/docs/integration/direct/rest/state-codes/#usa). Maximum length is 40 single-byte characters." }, "phone": { "type": "string", "format": "phone", "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en)." } }, "required": [ "line1", "city", "country_code" ] }, "phone": { "type": "object", "title": "Phone", "description": "The phone number.", "properties": { "country_code": { "type": "string", "description": "The country code portion of the phone number, in [E.164 format](https://www.itu.int/rec/T-REC-E.164-201011-I).", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "national_number": { "type": "string", "description": "The in-country phone number, in [E.164 format](https://www.itu.int/rec/T-REC-E.164-201011-I).", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" } } }, "merchant-info": { "type": "object", "title": "Merchant Information", "description": "The merchant business information that appears on the invoice.", "properties": { "email": { "type": "string", "format": "email", "description": "The merchant email address. This email must be listed in the merchant'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.", "maxLength": 260 }, "business_name": { "type": "string", "description": "The merchant's business name.", "maxLength": 100 }, "first_name": { "type": "string", "description": "The merchant's first name.", "maxLength": 256 }, "last_name": { "type": "string", "description": "The merchant's last name.", "maxLength": 256 }, "address": { "$ref": "#/components/schemas/address", "description": "The merchant's address." }, "phone": { "$ref": "#/components/schemas/phone", "description": "The merchant's phone number." }, "fax": { "$ref": "#/components/schemas/phone", "description": "The merchant's fax number." }, "website": { "type": "string", "format": "uri", "description": "The merchant's website.", "maxLength": 2048 }, "tax_id": { "type": "string", "description": "The merchant's tax ID.", "maxLength": 100 }, "additional_info": { "type": "string", "description": "Any additional information, such as business hours.", "maxLength": 40 } } }, "billing-info": { "type": "object", "title": "Billing Information", "description": "The billing information for the invoice recipient.", "properties": { "email": { "type": "string", "format": "email", "description": "The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.", "maxLength": 260 }, "phone": { "$ref": "#/components/schemas/phone", "description": "The invoice recipient's phone number." }, "first_name": { "type": "string", "description": "The invoice recipient's first name.", "maxLength": 30 }, "last_name": { "type": "string", "description": "The invoice recipient's last name.", "maxLength": 30 }, "business_name": { "type": "string", "description": "The invoice recipient's business name.", "maxLength": 100 }, "address": { "$ref": "#/components/schemas/address", "description": "The invoice recipient's billing address." }, "language": { "type": "string", "description": "The language in which the invoice recipient's email appears. 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 is sent in the language of the merchant's PayPal account.", "enum": [ "da_DK", "de_DE", "en_AU", "en_GB", "en_US", "es_ES", "es_XC", "fr_CA", "fr_FR", "fr_XC", "he_IL", "id_ID", "it_IT", "ja_JP", "nl_NL", "no_NO", "pl_PL", "pt_BR", "pt_PT", "ru_RU", "sv_SE", "th_TH", "tr_TR", "zh_CN", "zh_HK", "zh_TW", "zh_XC" ] }, "additional_info": { "type": "string", "description": "Any additional information about the recipient.", "maxLength": 40 } } }, "shipping-info": { "type": "object", "title": "Shipping Information", "description": "The shipping information for the invoice recipient.", "properties": { "first_name": { "type": "string", "description": "The first name of the recipient at the shipping address.", "maxLength": 256 }, "last_name": { "type": "string", "description": "The last name of the recipient at the shipping address.", "maxLength": 256 }, "business_name": { "type": "string", "description": "The business name of the recipient at the shipping address.", "maxLength": 480 }, "address": { "$ref": "#/components/schemas/address", "description": "The shipping address." } } }, "participant": { "type": "object", "title": "Participant", "description": "The participant information.", "properties": { "email": { "type": "string", "format": "email", "description": "The email address of the person who receives a copy of the invoice.", "maxLength": 260 } }, "required": [ "email" ] }, "currency": { "type": "object", "title": "Currency", "description": "The currency and amount for a financial transaction, such as a balance or payment due.", "properties": { "currency": { "type": "string", "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/)." }, "value": { "type": "string", "description": "The value, which might be:For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)." } }, "required": [ "currency", "value" ] }, "tax": { "type": "object", "title": "Tax", "description": "The tax information.", "properties": { "name": { "type": "string", "description": "The tax name.", "maxLength": 100 }, "percent": { "type": "number", "description": "The tax rate. Value is from `0` to `100`. Supports up to five decimal places.", "minimum": 0 }, "amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the calculated tax.", "readOnly": true } }, "required": [ "name", "percent" ] }, "discount": { "type": "object", "title": "Discount", "description": "The discount as a percent or an amount value. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.", "properties": { "percent": { "type": "number", "description": "The discount as a percentage value. Value is from `0` to `100`. Supports up to five decimal places." }, "amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the invoice-level discount. Value is from `0` to `1000000`. Supports up to two decimal places." } } }, "invoice-item": { "type": "object", "title": "Invoice Item", "description": "The invoice line item information.", "properties": { "name": { "type": "string", "description": "The item name.", "maxLength": 200 }, "description": { "type": "string", "description": "The item description.", "maxLength": 1000 }, "quantity": { "type": "number", "description": "The item quantity. Value is from `-10000` to `10000`. Supports up to five decimal places." }, "unit_price": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the item unit price. Value is from `-1000000` to `1000000`. Supports up to two decimal places." }, "tax": { "$ref": "#/components/schemas/tax" }, "date": { "type": "string", "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* *z*.", "format": "date" }, "discount": { "$ref": "#/components/schemas/discount", "description": "The item discount, as a percent or an amount value." }, "unit_of_measure": { "type": "string", "description": "The unit of measure for the invoiced item. For `AMOUNT` the `unit_price` 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.
", "enum": [ "QUANTITY", "HOURS", "AMOUNT" ] } }, "required": [ "name", "quantity", "unit_price" ] }, "payment-term": { "type": "object", "title": "Payment Term", "description": "The payment term of the invoice. If you specify `term_type`, you cannot specify `due_date`, and vice versa.", "properties": { "term_type": { "type": "string", "description": "The term when the invoice payment is due.", "enum": [ "DUE_ON_RECEIPT", "DUE_ON_DATE_SPECIFIED", "NET_10", "NET_15", "NET_30", "NET_45", "NET_60", "NET_90", "NO_DUE_DATE" ] }, "due_date": { "type": "string", "format": "date", "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* *z*." } } }, "shipping-cost": { "type": "object", "title": "Shipping Cost", "description": "The shipping cost, as a percent or amount value.", "properties": { "amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the shipping charge. Value is from `0` to `1000000`. Supports up to two decimal places." }, "tax": { "$ref": "#/components/schemas/tax", "description": "The tax percentage on the shipping amount." } } }, "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.", "properties": { "label": { "type": "string", "description": "The custom amount label.", "maxLength": 50 }, "amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the custom value. Value is from `-1000000` to `1000000`. Supports up to two decimal places." } } }, "payment-detail": { "type": "object", "title": "Payment Detail", "description": "The payment details.", "properties": { "type": { "type": "string", "description": "The payment type in an invoicing flow. The [record refund](/docs/api/invoicing/v1/#invoices_record-refund) method supports the `EXTERNAL` refund type. The `PAYPAL` refund type is supported for backward compatibility.", "enum": [ "PAYPAL", "EXTERNAL" ], "readOnly": true }, "transaction_id": { "type": "string", "description": "The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.", "readOnly": true }, "transaction_type": { "type": "string", "description": "The transaction type.", "enum": [ "SALE", "AUTHORIZATION", "CAPTURE" ], "readOnly": true }, "date": { "type": "string", "description": "The date when the invoice was paid, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "format": "date-time" }, "method": { "type": "string", "description": "The payment mode or method.", "enum": [ "BANK_TRANSFER", "CASH", "CHECK", "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "WIRE_TRANSFER", "OTHER" ] }, "note": { "type": "string", "description": "A note associated with the payment." }, "amount": { "$ref": "#/components/schemas/currency", "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." } }, "required": [ "method" ] }, "refund-detail": { "type": "object", "title": "Refund Detail", "description": "The invoicing refund details.", "properties": { "type": { "type": "string", "description": "The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The [record refund](/docs/api/invoicing/v1/#invoices_record-refund) method supports the `EXTERNAL` refund type. The `PAYPAL` refund type is supported for backward compatibility.", "enum": [ "PAYPAL", "EXTERNAL" ], "readOnly": true }, "transaction_id": { "type": "string", "description": "The ID of the PayPal refund transaction. Required for the `PAYPAL` refund type.", "readOnly": true }, "date": { "type": "string", "description": "The date when the invoice was refunded, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2014-02-27 PST`.", "format": "date-time" }, "note": { "type": "string", "description": "A note associated with the refund." }, "amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded." } } }, "metadata": { "type": "object", "title": "Metadata", "description": "The audit metadata.", "properties": { "created_date": { "type": "string", "format": "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 }, "cancelled_date": { "type": "string", "format": "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 }, "last_updated_date": { "type": "string", "format": "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 }, "first_sent_date": { "type": "string", "format": "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_date": { "type": "string", "format": "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 }, "payer_view_url": { "type": "string", "format": "uri", "description": "The URL for the payer's view of the invoice.", "readOnly": true } } }, "payment-summary": { "type": "object", "title": "Payment Summary", "description": "The payment and refund summary.", "properties": { "paypal": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the total paid or refunded through PayPal.", "readOnly": true }, "other": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the total paid or refunded through other sources.", "readOnly": true } } }, "file-attachment": { "type": "object", "title": "File Attachment", "description": "The file that is attached to an invoice or template.", "properties": { "name": { "type": "string", "description": "The name of the attached file." }, "url": { "type": "string", "format": "uri", "description": "The URL of the attached file. Use this URL to download the file." } } }, "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" ] } } }, "invoice": { "title": "Invoice", "type": "object", "description": "The invoice details.", "properties": { "id": { "type": "string", "description": "The ID of the invoice.", "readOnly": true }, "number": { "type": "string", "description": "The invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.", "maxLength": 25 }, "status": { "type": "string", "description": "The invoice status. When you [search for invoices](/docs/api/invoicing/v1/#search_search), you must specify this value as an array. For example, `\"status\": [\"REFUNDED\"]`. The status indicates the phase of an invoice in its lifecycle. The status also indicates whether the invoice is unpaid, partially paid, fully paid, partially refunded, or fully refunded. An invoice payment can be either:
Similarly, an invoice refund can be disconnected from an invoice. The merchant refunds a payment by check, wire transfer, or another method and manually records the refund. This table lists the typical order through which an invoice moves through status values:
StatusOccurs when
DRAFT

A merchant creates a draft invoice.

Note: A customer cannot pay an invoice with this status. A customer cannot pay an invoice until it has a status of SENT or UNPAID.
UNPAID

A merchant chooses to suppress the PayPal email notification when he or she sends the invoice through the API or the Create Invoice page, and then manually sends the invoice link in his or her own email.

To send an invoice without email notification, the merchant either:

  • Sets the notify_merchant and notify_customer query parameters to false when he or she sends the invoice.

  • Selects Share link myself from the Send menu when he or she sends the invoice through the web UI Create Invoice page.

SENT

A merchant accepts the default PayPal email notification when he or she sends the invoice through the API or the Create Invoice page. PayPal automatically emails the invoice to the customer and a Pay button appears on the invoice, which enables the customer to pay the invoice. In a web app, the invoice appears as Unpaid (sent).

SCHEDULED

A merchant schedules an invoice to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to SENT.

PARTIALLY_PAID

A customer makes a partial payment for the invoice through one of these methods:

PAYMENT_PENDING

A customer pays an invoice but the payment is pending for one of these reasons:

  • The payment is an uncleared eCheck.
  • The merchant must either accept the payment before it clears or deny the payment.
  • PayPal risk is reviewing the payment.
Note: Most payments never go into a payment-pending state.
PAID

A customer fully pays the invoice through one of these methods:

MARKED_AS_PAID

A customer makes a disconnected payment for the balance of the invoice. The merchant manually marks the invoice as paid.

CANCELLED

A merchant or customer cancels a sent invoice. You can cancel an invoice in SENT or UNPAID status.

REFUNDED

A merchant fully refunds an invoice through one these methods:

PARTIALLY_REFUNDED

A merchant partially refunds an invoice through one or both of these methods:

MARKED_AS_REFUNDED

A merchant makes a disconnected refund, such as a check payment, for the invoice balance and manually marks the invoice as fully refunded.

Note: A merchant can only mark a marked-as-paid invoice as refunded.
", "enum": [ "DRAFT", "UNPAID", "SENT", "SCHEDULED", "PARTIALLY_PAID", "PAYMENT_PENDING", "PAID", "MARKED_AS_PAID", "CANCELLED", "REFUNDED", "PARTIALLY_REFUNDED", "MARKED_AS_REFUNDED" ], "readOnly": true }, "merchant_info": { "$ref": "#/components/schemas/merchant-info", "description": "The merchant information, such as business name, email, address, and so on." }, "billing_info": { "type": "array", "description": "An array of billing information for the invoice recipient.
Note: This value is an array with only one element.
", "minItems": 1, "maxItems": 1, "items": { "description": "The billing information for the invoice recipient.", "$ref": "#/components/schemas/billing-info" } }, "shipping_info": { "$ref": "#/components/schemas/shipping-info", "description": "The shipping information for the recipient of the invoice." }, "cc_info": { "type": "array", "description": "An array of email addresses to which PayPal sends a copy of the invoice.", "items": { "$ref": "#/components/schemas/participant", "description": "The participant information." } }, "items": { "type": "array", "description": "An array of invoice line item information.", "maxItems": 100, "items": { "$ref": "#/components/schemas/invoice-item", "description": "The invoice line item information." } }, "invoice_date": { "type": "string", "format": "date", "description": "The invoice date as specified by the sender, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6)." }, "payment_term": { "$ref": "#/components/schemas/payment-term", "description": "The payment due date of the invoice. If you include `due_date`, the `term_type` value is ignored." }, "reference": { "type": "string", "description": "The reference data, such as PO number.", "maxLength": 60 }, "discount": { "$ref": "#/components/schemas/discount", "description": "The invoice level discount, as a percent or an amount value." }, "shipping_cost": { "$ref": "#/components/schemas/shipping-cost", "description": "The shipping amount, as a percent or an amount value." }, "custom": { "$ref": "#/components/schemas/custom-amount", "description": "The custom amount to apply to an invoice. If you include a label, you must include a custom amount." }, "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 merchants in `India`, `Brazil`, or `Israel`.
", "default": false }, "minimum_amount_due": { "$ref": "#/components/schemas/currency", "description": "The minimum amount allowed for a partial payment. Valid only if `allow_partial_payment` is `true`." }, "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": false }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether the unit price includes tax.", "default": false }, "terms": { "type": "string", "description": "The general terms of the invoice.", "maxLength": 4000 }, "note": { "type": "string", "description": "A note to the invoice recipient. The note also appears on the invoice notification email.", "maxLength": 4000 }, "merchant_memo": { "type": "string", "description": "A private bookkeeping memo for the merchant.", "maxLength": 500 }, "logo_url": { "type": "string", "format": "uri", "description": "The full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.", "maxLength": 4000 }, "total_amount": { "$ref": "#/components/schemas/currency", "description": "The total amount of the invoice.", "readOnly": true }, "payments": { "type": "array", "description": "An array of payment details for the invoice.", "maxItems": 1, "items": { "$ref": "#/components/schemas/payment-detail", "description": "The payment details for the invoice." }, "readOnly": true }, "refunds": { "type": "array", "description": "An array of refund details for the invoice.", "maxItems": 1, "items": { "description": "The refund details for the invoice.", "$ref": "#/components/schemas/refund-detail" }, "readOnly": true }, "metadata": { "$ref": "#/components/schemas/metadata", "description": "The audit information for the invoice.", "readOnly": true }, "paid_amount": { "$ref": "#/components/schemas/payment-summary", "description": "The payment summary of the invoice. Includes the amount paid through PayPal and other sources.", "readOnly": true }, "refunded_amount": { "$ref": "#/components/schemas/payment-summary", "description": "The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.", "readOnly": true }, "attachments": { "type": "array", "description": "An array of PayPal file IDs for the files that are attached to an invoice. You can attach up to five files.", "readOnly": true, "items": { "description": "The file that is attached to an invoice or template.", "$ref": "#/components/schemas/file-attachment" } }, "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 merchants in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
", "default": false }, "template_id": { "type": "string", "description": "This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.
Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The `template_id` is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.
", "default": "PayPal system template" }, "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 } } }, "required": [ "merchant_info" ] }, "invoices": { "type": "object", "title": "Invoices", "minItems": 1, "description": "A list of merchant invoices. Can include the total invoices count and HATEOAS links for navigation.", "properties": { "total_count": { "type": "integer", "description": "The total number of invoices that match the search criteria.", "readOnly": true }, "invoices": { "type": "array", "description": "An array of invoice-level details.
Note: This array does not return item details for the invoice.
", "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", "readOnly": true } } } }, "search": { "type": "object", "title": "Search", "description": "The invoice search parameters.", "properties": { "email": { "type": "string", "description": "The initial letters of the email address." }, "recipient_first_name": { "type": "string", "description": "The initial letters of the recipient's first name." }, "recipient_last_name": { "type": "string", "description": "The initial letters of the recipient's last name." }, "recipient_business_name": { "type": "string", "description": "The initial letters of the recipient's business name." }, "number": { "type": "string", "description": "Any part of the invoice number." }, "status": { "type": "string", "description": "The invoice status. To search by status, specify this value as an array. For example, `\"status\": [\"REFUNDED\"]`. The status indicates the phase of the invoice in its lifecycle:
StatusOccurs when
CANCELLED

A merchant or customer cancels a sent invoice.

DRAFT

A merchant creates a draft invoice.

Note: A customer cannot pay an invoice until a merchant sends it.
MARKED_AS_PAID

A merchant marks an invoice as paid after he or she receives a check or cash payment for the invoice.

MARKED_AS_REFUNDED

A merchant marks an invoice as refunded.

Note: A merchant can only mark a marked-as-paid invoice as refunded.
PAID

A customer fully pays an invoice. It is marked as paid through one or both of these methods:

  • A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice.
  • A customer makes an online payment for the invoice.
PARTIALLY_PAID

A merchant or customer fully pays an invoice through one or both of these methods:

  • A merchant marks an invoice as paid after he or she receives a check or cash payment from the customer for the invoice.
  • A customer makes an online payment for the invoice.
PARTIALLY_REFUNDED

A merchant partially refunds an invoice through one or both of these methods:

PAYMENT_PENDING

A customer pays an invoice but the payment is pending for one of these reasons:

  • The payment is an uncleared eCheck.
  • The payment is in an accept or deny state upon which the merchant must act.
  • PayPal risk is reviewing the payment.
Note: Most payments never go into a payment-pending state.
REFUNDED

A merchant fully refunds an invoice through one or both of these methods:

SCHEDULED

A merchant schedules an invoice to be emailed by PayPal on a specified date.

SENT

A merchant sends an invoice to the customer.

After the merchant sends the invoice:

  • PayPal emails the invoice to the customer.
  • A Payment button appears on the invoice. The customer can now pay the invoice.
  • In a web app, the invoice appears as Unpaid (sent).
UNPAID

A merchant sends an invoice and sets the notify_merchant and notify_customer query parameters to false to suppress the PayPal email notification. Then, the merchant manually sends the invoice link in his or her own email.

", "enum": [ "DRAFT", "SENT", "SCHEDULED", "PAID", "MARKED_AS_PAID", "CANCELLED", "REFUNDED", "PARTIALLY_REFUNDED", "MARKED_AS_REFUNDED" ] }, "lower_total_amount": { "type": "string", "description": "The lower limit of the total amount." }, "upper_total_amount": { "type": "string", "description": "The upper limit of the total amount." }, "start_invoice_date": { "type": "string", "format": "date", "description": "The start date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "end_invoice_date": { "type": "string", "format": "date", "description": "The end date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "start_due_date": { "type": "string", "format": "date", "description": "The start due date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "end_due_date": { "type": "string", "format": "date", "description": "The end due date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "start_payment_date": { "type": "string", "format": "date", "description": "The start payment date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "end_payment_date": { "type": "string", "format": "date", "description": "The end payment date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "start_creation_date": { "type": "string", "format": "date", "description": "The start creation date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "end_creation_date": { "type": "string", "format": "date", "description": "The end creation date for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*." }, "page": { "type": "number", "description": "The zero-relative start index of the entire list of merchant invoices to return in the response. So, a combination of `page=0` and `page_size=20` returns the first 20 invoices. A combination of `page=20` and `page_size=20` returns the next 20 invoices." }, "page_size": { "type": "number", "description": "The page size for the search results." }, "total_count_required": { "type": "boolean", "description": "Indicates whether the response shows the total count.", "default": false }, "archived": { "type": "boolean", "description": "Indicates whether to list merchant-archived invoices in the response. If `true`, response lists only merchant-archived invoices. If `false`, response lists only unarchived invoices. If `null`, response lists all invoices." } } }, "notification": { "type": "object", "title": "Notification", "description": "The email or SMS notification.", "properties": { "subject": { "type": "string", "description": "The subject of the notification. Default is a generic subject." }, "note": { "type": "string", "description": "A note to the payer." }, "send_to_merchant": { "type": "boolean", "description": "Indicates whether to send a copy of the email to the merchant.", "default": true }, "cc_emails": { "type": "array", "description": "An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the `cc_info` array of the invoice.
", "maxItems": 100, "items": { "type": "string", "description": "A CC: email to which to send a notification email.", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" } } } }, "cancel-notification": { "type": "object", "title": "Cancel Notification", "description": "Cancels an email or SMS notification.", "properties": { "subject": { "type": "string", "description": "The subject of the notification. If left blank we include a generic subject." }, "note": { "type": "string", "description": "A note to the payer." }, "send_to_merchant": { "type": "boolean", "description": "Indicates whether to send the notification to the merchant.", "default": true }, "send_to_payer": { "type": "boolean", "description": "Indicates whether to send the notification to the payer.", "default": true }, "cc_emails": { "type": "array", "description": "An array of one or more CC: emails to which to send notification emails. If you omit this parameter, the API sends notification emails to all CC: email addresses that are part of the invoice.
Note: Additional email addresses are not supported.
", "maxItems": 100, "items": { "type": "string", "description": "A CC: email to which to send a notification email.", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" } } } }, "qr_code": { "type": "object", "title": "QR Code", "description": "The base64-encoded image of the `image/png` type.", "properties": { "image": { "type": "string", "description": "The base64-encoded image of the `image/png` type." } } }, "invoice_number": { "type": "object", "title": "Invoice Number", "description": "The invoice number.", "properties": { "number": { "type": "string", "description": "The invoice number. If you omit this value from the request, the default is the number that the API automatically increments from the last number." } } }, "email": { "title": "Email", "type": "string", "format": "email", "description": "The participant's email address." }, "template-data": { "type": "object", "title": "Template Data", "description": "The template data.", "properties": { "merchant_info": { "$ref": "#/components/schemas/merchant-info" }, "billing_info": { "type": "array", "description": "The billing information of the invoice recipient.
Note: This value is an array with only one element.
", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/billing-info" } }, "shipping_info": { "$ref": "#/components/schemas/shipping-info" }, "cc_info": { "type": "array", "description": "An array of email addresses to which PayPal sends a copy of the invoice.", "items": { "$ref": "#/components/schemas/email", "description": "The participant's email address." } }, "items": { "type": "array", "description": "An array of invoice line item information. The maximum items for an invoice is `100`.", "maxItems": 100, "items": { "$ref": "#/components/schemas/invoice-item" } }, "payment_term": { "$ref": "#/components/schemas/payment-term" }, "reference": { "type": "string", "description": "The reference data, such as a PO number.", "maxLength": 60 }, "discount": { "$ref": "#/components/schemas/discount", "description": "The invoice level discount, as a percent or an amount value." }, "shipping_cost": { "$ref": "#/components/schemas/shipping-cost", "description": "The shipping cost, as a percent or an amount value." }, "custom": { "$ref": "#/components/schemas/custom-amount" }, "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 merchants in `India`, `Brazil`, or `Israel`.
", "default": false }, "minimum_amount_due": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the minimum allowed for a partial payment. Valid only when `allow_partial_payment` is `true`." }, "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": false }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether the unit price includes tax.", "default": false }, "terms": { "type": "string", "description": "The general terms of the invoice.", "maxLength": 4000 }, "note": { "type": "string", "description": "A note to the invoice recipient. This note also appears on the invoice notification email.", "maxLength": 4000 }, "merchant_memo": { "type": "string", "description": "A private bookkeeping memo for the merchant.", "maxLength": 150 }, "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": 4000 }, "total_amount": { "$ref": "#/components/schemas/currency", "description": "The currency and amount of the invoice total.", "readOnly": true }, "attachments": { "type": "array", "description": "An array of PayPal file IDs for the files that are attached to an invoice. The maximum number of files is `5`.", "items": { "$ref": "#/components/schemas/file-attachment" } } }, "required": [ "merchant_info" ] }, "template-settings-metadata": { "type": "object", "title": "Template Settings Metadata", "description": "The template settings metadata.", "properties": { "hidden": { "type": "boolean", "description": "Indicates whether to show or hide this field.", "default": false } } }, "template-settings": { "type": "object", "title": "Template Settings", "description": "The template settings.", "properties": { "field_name": { "type": "string", "description": "The field name in `template_data` for which to map corresponding display preferences.", "enum": [ "items.quantity", "items.description", "items.date", "items.discount", "items.tax", "discount", "shipping", "custom" ] }, "display_preference": { "$ref": "#/components/schemas/template-settings-metadata" } } }, "template": { "type": "object", "title": "Template", "description": "The invoicing template.", "properties": { "template_id": { "type": "string", "description": "The ID of the template.", "readOnly": true }, "name": { "type": "string", "description": "The template name.
Note: The template name must be unique.
" }, "default": { "type": "boolean", "description": "Indicates whether this template is the default merchant template. A merchant can have one default template." }, "template_data": { "$ref": "#/components/schemas/template-data" }, "settings": { "type": "array", "description": "An array of template settings that describe which fields to show or hide when creating an invoice.", "items": { "$ref": "#/components/schemas/template-settings" } }, "unit_of_measure": { "type": "string", "description": "The unit of measure for the template.", "enum": [ "HOURS", "QUANTITY", "AMOUNT" ] }, "custom": { "type": "boolean", "description": "Indicates whether this template is a merchant-created custom template. The system generates non-custom templates.", "readOnly": true }, "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 } } } }, "templates": { "type": "object", "title": "Templates", "minItems": 1, "description": "A merchant-created template with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.", "properties": { "addresses": { "type": "array", "description": "An array of postal addresses in the user's PayPal profile.", "items": { "description": "The base address to use as billing address in a payment or to extend a shipping address.", "$ref": "#/components/schemas/address" } }, "emails": { "type": "array", "description": "An array of email addresses in the user's PayPal profile.", "items": { "description": "An email in the user's PayPal profile.", "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" } }, "phones": { "type": "array", "description": "An array of phone numbers in the user's PayPal profile.", "items": { "$ref": "#/components/schemas/phone" } }, "templates": { "type": "array", "description": "The details for each template. If `fields` is `none`, returns only the template name, ID, and default status.", "items": { "$ref": "#/components/schemas/template" } }, "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 } } } } } } }