Invoices API

Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide.

Invoices (resource group)

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.

Generate invoice number

POST/v2/invoicing/generate-next-invoice-number
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.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/generate-next-invoice-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.
  • invoice_number

    string

    The invoice number. If you omit this value, the default is the auto-incremented number from the last number.

    Read only.

    Maximum length: 25.

Sample Request

{
  "invoice_number": "ee0044"
}

Sample Response

{
  "invoice_number": "ee0044"
}

List invoices

GET/v2/invoicing/invoices
Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.

Query parameters

  • page

    integer

    The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.

    Minimum value: 1.

    Maximum value: 1000.

  • page_size

    integer

    The maximum number of invoices to return in the response.

    Minimum value: 1.

    Maximum value: 100.

  • total_required

    boolean

    Indicates whether the to show total_pages and total_items in the response.

  • fields

    string

    A comma-separated list of additional fields to return, if available.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices?total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.
  • total_pages

    integer

    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

    Read only.

  • total_items

    integer

    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.

    Read only.

  • items

    array (contains the invoice object)

    The list of invoices that match the search criteria.

    Read only.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "total_items": 2,
  "total_pages": 1,
  "items": [
    {
      "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
      "status": "DRAFT",
      "detail": {
        "invoice_number": "#123",
        "reference": "deal-ref",
        "invoice_date": "2018-11-12",
        "currency_code": "USD",
        "note": "Thank you for your business.",
        "term": "No refunds after 30 days.",
        "memo": "This is a long contract",
        "payment_term": {
          "term_type": "NET_10",
          "due_date": "2018-11-22"
        },
        "metadata": {
          "create_time": "2018-11-12T08:00:20Z",
          "recipient_view_url": "https://www.paypal.com/invoice/p/#Z56S5LLAQ52LCPZ5",
          "invoicer_view_url": "https://www.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"
        }
      },
      "invoicer": {
        "email_address": "merchant@example.com"
      },
      "primary_recipients": [
        {
          "billing_info": {
            "email_address": "bill-me@example.com"
          }
        }
      ],
      "amount": {
        "currency_code": "USD",
        "value": "74.21"
      },
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",
          "rel": "send",
          "method": "POST"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    },
    {
      "id": "INV2-NP6M-C9A8-ZBDA-3TEX",
      "status": "SCHEDULED",
      "detail": {
        "invoice_number": "0001",
        "invoice_date": "2018-05-14",
        "currency_code": "USD",
        "payment_term": {
          "due_date": "2018-05-15"
        },
        "metadata": {
          "create_time": "2018-05-15T17:24:12Z"
        }
      },
      "invoicer": {
        "email_address": "merchant@example.com"
      },
      "primary_recipients": [
        {
          "billing_info": {
            "email_address": "recipient@example.com"
          }
        }
      ],
      "amount": {
        "currency_code": "USD",
        "value": "32.00"
      },
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-NP6M-C9A8-ZBDA-3TEX/payments",
          "rel": "record-payment",
          "method": "POST"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices?page=1&page_size=20&total_required=false",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Create draft invoice

POST/v2/invoicing/invoices
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.
.

Request body

  • id

    string

    The ID of the invoice.

    Maximum length: 30.

  • parent_id

    string

    The parent ID to an invoice that defines the group invoice to which the invoice is related.

    Maximum length: 30.

  • status

    enum

    The status of the invoice.

    The possible values are:

    • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
    • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
    • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
    • PAID. The payer has paid for the invoice.
    • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
    • CANCELLED. The invoice has been cancelled by the invoicer.
    • REFUNDED. The invoice has been refunded by the invoicer.
    • PARTIALLY_PAID. The payer has partially paid for the invoice.
    • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
    • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
    • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
    • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
  • detail

    object

    required

    The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

  • invoicer

    object

    The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

  • primary_recipients

    array (contains the recipient_info object)

    The billing and shipping information. Includes name, email, address, phone and language.

  • additional_recipients

    array (contains the email_address object)

    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

    array (contains the item object)

    An array of invoice line item information.

  • configuration

    object

    The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

  • amount

    object

    The invoice amount summary of item total, discount, tax total and shipping..

  • due_amount

    object

    The due amount, which is the balance amount outstanding after payments.

  • gratuity

    object

    The amount paid by the payer as gratuity to the invoicer.

  • payments

    object

    List of payments registered against the invoice..

  • refunds

    object

    List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "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"
        }
      }
    }
  }
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows invoice details.
  • href

    string

    The complete target URL. To make the related call, combine the method with this URI Template-formatted 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

    string

    The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

  • method

    enum

    The HTTP method required to make the related call.

    Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

Sample Response

{
  "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  "status": "DRAFT",
  "detail": {
    "invoice_number": "#123",
    "reference": "deal-ref",
    "invoice_date": "2018-11-12",
    "currency_code": "USD",
    "note": "Thank you for your business.",
    "term": "No refunds after 30 days.",
    "memo": "This is a long contract",
    "payment_term": {
      "term_type": "NET_10",
      "due_date": "2018-11-22"
    },
    "metadata": {
      "create_time": "2018-11-12T08:00:20Z",
      "recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",
      "invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": "merchant@example.com",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://example.com",
    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "2-4"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "bill-me@example.com",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ],
        "additional_info_value": "add-info"
      },
      "shipping_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga Mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25",
        "amount": {
          "currency_code": "USD",
          "value": "3.27"
        }
      },
      "discount": {
        "percent": "5",
        "amount": {
          "currency_code": "USD",
          "value": "2.5"
        }
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Yoga T Shirt",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25",
        "amount": {
          "currency_code": "USD",
          "value": "0.34"
        }
      },
      "discount": {
        "amount": {
          "currency_code": "USD",
          "value": "5.00"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "20.00"
      }
    },
    "allow_tip": true,
    "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"
      }
    }
  },
  "due_amount": {
    "currency_code": "USD",
    "value": "74.21"
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",
      "rel": "send",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/update",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments",
      "rel": "record-payment",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code",
      "rel": "qr-code",
      "method": "POST"
    }
  ]
}

Delete invoice

DELETE/v2/invoicing/invoices/{invoice_id}
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.

Path parameters

  • invoice_id

    string

    required

    The ID of the draft invoice to delete.

Sample Request

curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

    Sample Response

    204 No content

    Fully update invoice

    PUT/v2/invoicing/invoices/{invoice_id}
    Fully updates an invoice, by ID. In the JSON request body, include a complete invoice object. This call does not support partial updates.

    Query parameters

    • send_to_recipient

      boolean

      Indicates whether to send the invoice update notification to the recipient.

    • send_to_invoicer

      boolean

      Indicates whether to send the invoice update notification to the merchant.

    Path parameters

    • invoice_id

      string

      required

      The ID of the invoice to update.

    Request body

    • id

      string

      The ID of the invoice.

      Maximum length: 30.

    • parent_id

      string

      The parent ID to an invoice that defines the group invoice to which the invoice is related.

      Maximum length: 30.

    • status

      enum

      The status of the invoice.

      The possible values are:

      • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
      • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
      • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
      • PAID. The payer has paid for the invoice.
      • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
      • CANCELLED. The invoice has been cancelled by the invoicer.
      • REFUNDED. The invoice has been refunded by the invoicer.
      • PARTIALLY_PAID. The payer has partially paid for the invoice.
      • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
      • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
      • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
      • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.
    • detail

      object

      required

      The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

    • invoicer

      object

      The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

    • primary_recipients

      array (contains the recipient_info object)

      The billing and shipping information. Includes name, email, address, phone and language.

    • additional_recipients

      array (contains the email_address object)

      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

      array (contains the item object)

      An array of invoice line item information.

    • configuration

      object

      The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

    • amount

      object

      The invoice amount summary of item total, discount, tax total and shipping..

    • due_amount

      object

      The due amount, which is the balance amount outstanding after payments.

    • gratuity

      object

      The amount paid by the payer as gratuity to the invoicer.

    • payments

      object

      List of payments registered against the invoice..

    • refunds

      object

      List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

    Sample Request

    curl -v -X PUT https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "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"
      }
    }
  }
}'

    Response

    A successful request returns the HTTP 204 No Content status code with no JSON response body.
    • id

      string

      The ID of the invoice.

      Read only.

      Maximum length: 30.

    • parent_id

      string

      The parent ID to an invoice that defines the group invoice to which the invoice is related.

      Read only.

      Maximum length: 30.

    • status

      enum

      The status of the invoice.

      The possible values are:

      • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
      • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
      • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
      • PAID. The payer has paid for the invoice.
      • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
      • CANCELLED. The invoice has been cancelled by the invoicer.
      • REFUNDED. The invoice has been refunded by the invoicer.
      • PARTIALLY_PAID. The payer has partially paid for the invoice.
      • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
      • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
      • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
      • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.

      Read only.

    • detail

      object

      The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

    • invoicer

      object

      The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

    • primary_recipients

      array (contains the recipient_info object)

      The billing and shipping information. Includes name, email, address, phone and language.

    • additional_recipients

      array (contains the email_address object)

      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

      array (contains the item object)

      An array of invoice line item information.

    • configuration

      object

      The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

    • amount

      object

      The invoice amount summary of item total, discount, tax total and shipping..

    • due_amount

      object

      The due amount, which is the balance amount outstanding after payments.

      Read only.

    • gratuity

      object

      The amount paid by the payer as gratuity to the invoicer.

      Read only.

    • payments

      object

      List of payments registered against the invoice..

    • refunds

      object

      List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    Sample Response

    {
  "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"
    },
    "metadata": {
      "create_time": "2018-11-12T08:00:20Z",
      "recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",
      "invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": "merchant@example.com",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://example.com",
    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "2-4"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "bill-me@example.com",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ],
        "additional_info_value": "add-info"
      },
      "shipping_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga Mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25",
        "amount": {
          "currency_code": "USD",
          "value": "3.27"
        }
      },
      "discount": {
        "percent": "5",
        "amount": {
          "currency_code": "USD",
          "value": "2.5"
        }
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Yoga t-shirt",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25",
        "amount": {
          "currency_code": "USD",
          "value": "0.34"
        }
      },
      "discount": {
        "amount": {
          "currency_code": "USD",
          "value": "5.00"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "20.00"
      }
    },
    "allow_tip": true,
    "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"
      }
    }
  },
  "due_amount": {
    "currency_code": "USD",
    "value": "74.21"
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",
      "rel": "send",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/update",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

    Show invoice details

    GET/v2/invoicing/invoices/{invoice_id}
    Shows details for an invoice, by ID.

    Path parameters

    • invoice_id

      string

      required

      The ID of the invoice for which to show details.

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.
    • id

      string

      The ID of the invoice.

      Read only.

      Maximum length: 30.

    • parent_id

      string

      The parent ID to an invoice that defines the group invoice to which the invoice is related.

      Read only.

      Maximum length: 30.

    • status

      enum

      The status of the invoice.

      The possible values are:

      • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
      • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
      • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
      • PAID. The payer has paid for the invoice.
      • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
      • CANCELLED. The invoice has been cancelled by the invoicer.
      • REFUNDED. The invoice has been refunded by the invoicer.
      • PARTIALLY_PAID. The payer has partially paid for the invoice.
      • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
      • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
      • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
      • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.

      Read only.

    • detail

      object

      The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

    • invoicer

      object

      The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

    • primary_recipients

      array (contains the recipient_info object)

      The billing and shipping information. Includes name, email, address, phone and language.

    • additional_recipients

      array (contains the email_address object)

      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

      array (contains the item object)

      An array of invoice line item information.

    • configuration

      object

      The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

    • amount

      object

      The invoice amount summary of item total, discount, tax total and shipping..

    • due_amount

      object

      The due amount, which is the balance amount outstanding after payments.

      Read only.

    • gratuity

      object

      The amount paid by the payer as gratuity to the invoicer.

      Read only.

    • payments

      object

      List of payments registered against the invoice..

    • refunds

      object

      List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    Sample Response

    {
  "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  "status": "DRAFT",
  "detail": {
    "invoice_number": "#123",
    "reference": "deal-ref",
    "invoice_date": "2018-11-12",
    "currency_code": "USD",
    "note": "Thank you for your business.",
    "term": "No refunds after 30 days.",
    "memo": "This is a long contract",
    "payment_term": {
      "term_type": "NET_10",
      "due_date": "2018-11-22"
    },
    "metadata": {
      "create_time": "2018-11-12T08:00:20Z",
      "recipient_view_url": "https://www.paypal.com/invoice/p/#Z56S5LLAQ52LCPZ5",
      "invoicer_view_url": "https://www.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": "merchant@example.com",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://example.com",
    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "2-4"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "bill-me@example.com",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ],
        "additional_info_value": "add-info"
      },
      "shipping_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga Mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25",
        "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"
      }
    }
  },
  "due_amount": {
    "currency_code": "USD",
    "value": "74.21"
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/send",
      "rel": "send",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments",
      "rel": "record-payment",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code",
      "rel": "qr-code",
      "method": "POST"
    }
  ]
}

    Cancel sent invoice

    POST/v2/invoicing/invoices/{invoice_id}/cancel
    Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.

    Path parameters

    • invoice_id

      string

      required

      The ID of the invoice to cancel.

    Request body

    • subject

      string

      The subject of the email that is sent as a notification to the recipient.

      Maximum length: 4000.

    • note

      string

      A note to the payer.

      Maximum length: 4000.

    • send_to_invoicer

      boolean

      Indicates whether to send a copy of the email to the merchant.

    • send_to_recipient

      boolean

      Indicates whether to send a copy of the email to the recipient.

    • additional_recipients

      array (contains the email_address object)

      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.

    Sample Request

    curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "subject": "Invoice Cancelled",
  "note": "Cancelling the invoice",
  "send_to_invoicer": true,
  "send_to_recipient": true,
  "additional_recipients": [
    "user@example.com"
  ]
}'

    Response

    A successful request returns the HTTP 204 No Content status code with no JSON response body.

      Sample Response

      204 No Content

      Generate QR code

      POST/v2/invoicing/invoices/{invoice_id}/generate-qr-code
      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.

      Path parameters

      • invoice_id

        string

        required

        The ID of the invoice for which to generate a QR code.

      Request body

      • width

        integer

        The width, in pixels, of the QR code image. Value is from 150 to 500.

      • height

        integer

        The height, in pixels, of the QR code image. Value is from 150 to 500.

      • action

        string

        The type of URL for which to generate a QR code. Valid values are pay and details.

        Maximum length: 7.

        Pattern: (?i)^(pay|details)$.

      Sample Request

      curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/generate-qr-code \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "width": 400,
  "height": 400
}'

      Response

      A successful request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a PNG image.

        Sample Response

        "--95dbdbed-7536-4c24-b5ca-bcdbc0006612 Content-Disposition: form-data; name=\"image\" Content-Type: application/octet-stream iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABxUlEQVR42u2WMY7kIBBFq0VA1n0BS1yDjCvZF7DxBdxXIuMaSFzAzgiQaz6t9mxLm1AbrCYYy4H1AlT1f9XHxH89lX7Z/2KJKN3CMIW6FCInYplLPtisoU6FTyHzti6RN5tPm+5ixrtTp0uP8g8s744eMS1yxvikNEOJz966GPTLaOL1fmjaxfAkaLCy2t2Hl10sPUIaNY1araFhCat3TbODDPkZ68Ii1sqfX62c1rzP62W8uWG0aiMaxSyvpS4hez2MzXkZg+FL4NNCwku/XtZ8g/Be550+Pe9jWj0x41rt1ngZyxzYa+NpmDjNMlYx1yhhs2glM8vY3IQ3qGWz9Tqvk7F3cGyYNd3KQDKGSWFGDjFNIZ8yhuWgR8gb5jR8+9bJ8rPUCd3oYbY4VcQqaWSYWRGcdnhnSS+D6lhKJIE5+JrTXtaquDtzuuypXrV0stRKwLAUzFodnYjxERP28ihtLw8WsbQE7JbxCD9SmxMxfsUYpiZ7lxYWMewltzuqKMz4n13tYi3vl6jW2FJQynBH+Za7Zie6sZRhNVXLTkqTmGUE5xSRu5dv3Qz3uYdj0bwkFLGWfxxoJMXx28tO9vu/9oPYF0bR/hBeOiwMAAAAAElFTkSuQmCC --95dbdbed-7536-4c24-b5ca-bcdbc0006612--"

        Record payment for invoice

        POST/v2/invoicing/invoices/{invoice_id}/payments
        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.

        Path parameters

        • invoice_id

          string

          required

          The ID of the invoice to mark as paid.

        Request body

        • type

          enum

          The payment type in an invoicing flow which can be PayPal or an external cash or check payment.

          The possible values are:

          • PAYPAL. The payment type is PayPal.
          • EXTERNAL. The payment type is an external cash or a check payment.
        • payment_id

          string

          The ID for a PayPal payment transaction. Required for the PAYPAL payment type.

          Maximum length: 22.

        • payment_date

          string

          The date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.

        • method

          enum

          required

          The payment mode or method through which the invoicer can accept the payment.

          The possible values are:

          • BANK_TRANSFER. Payments can be received through bank transfers.
          • CASH. Payments can be received as cash.
          • CHECK. Payments can be received as check.
          • CREDIT_CARD. Payments can be received through credit card payments.
          • DEBIT_CARD. Payments can be received through debit card payments.
          • PAYPAL. Payments can be received through paypal payments.
          • WIRE_TRANSFER. Payments can be received through wire transfer.
          • OTHER. Payments can be received through other modes.
        • note

          string

          A note associated with an external cash or check payment.

          Maximum length: 2000.

        • amount

          object

          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

          object

          The recipient's shipping information. Includes the user's contact information, which includes name and address.

        Sample Request

        curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "method": "BANK_TRANSFER",
  "payment_date": "2018-05-01",
  "amount": {
    "currency_code": "USD",
    "value": "10.00"
  }
}'

        Response

        A successful request returns the HTTP 200 Created status code and a reference to the recorded payment.
        • payment_id

          string

          The ID for the invoice payment.

          Read only.

        Sample Response

        {
  "payment_id": "EXTR-86F38350LX4353815"
}

        Delete external payment

        DELETE/v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}
        Deletes an external payment, by invoice ID and transaction ID.

        Path parameters

        • invoice_id

          string

          required

          The ID of the invoice from which to delete an external payment transaction.

        • transaction_id

          string

          required

          The ID of the external payment transaction to delete.

        Sample Request

        curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments/EXTR-86F38350LX4353815 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

        Response

        A successful request returns the HTTP 204 No Content status code with no JSON response body.

          Sample Response

          204 No Content

          Record refund for invoice

          POST/v2/invoicing/invoices/{invoice_id}/refunds
          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.

          Path parameters

          • invoice_id

            string

            required

            The ID of the invoice to mark as refunded.

          Request body

          • type

            enum

            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.

            The possible values are:

            • PAYPAL. The payment type is PayPal.
            • EXTERNAL. The payment type is an external cash or a check payment.
          • refund_id

            string

            The ID for a PayPal payment transaction. Required for the PAYPAL payment type.

            Maximum length: 22.

          • refund_date

            string

            The date when the invoice was refunded, in Internet date format. For example, 2014-02-27.

          • amount

            object

            The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.

          • method

            enum

            required

            The payment mode or method through which the invoicer can accept the payments.

            The possible values are:

            • BANK_TRANSFER. Payments can be received through bank transfers.
            • CASH. Payments can be received as cash.
            • CHECK. Payments can be received as check.
            • CREDIT_CARD. Payments can be received through credit card payments.
            • DEBIT_CARD. Payments can be received through debit card payments.
            • PAYPAL. Payments can be received through paypal payments.
            • WIRE_TRANSFER. Payments can be received through wire transfer.
            • OTHER. Payments can be received through other modes.

          Sample Request

          curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/refunds \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "method": "BANK_TRANSFER",
  "refund_date": "2018-05-21",
  "amount": {
    "currency_code": "USD",
    "value": "5.00"
  }
}'

          Response

          A successful request returns the HTTP 200 Created status code and a reference to the recorded refund.
          • refund_id

            string

            The ID of the refund of an invoice payment.

            Read only.

          Sample Response

          {
  "refund_id": "EXTR-2LG703375E477444T"
}

          Delete external refund

          DELETE/v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}
          Deletes an external refund, by invoice ID and transaction ID.

          Path parameters

          • invoice_id

            string

            required

            The ID of the invoice from which to delete the external refund transaction.

          • transaction_id

            string

            required

            The ID of the external refund transaction to delete.

          Sample Request

          curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-333R-YUQL-YNNN-D7WF/refunds/EXTR-2LG703375E477444T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

          Response

          A successful request returns the HTTP 204 No Content status code with no JSON response body.

            Sample Response

            204 No Content

            Send invoice reminder

            POST/v2/invoicing/invoices/{invoice_id}/remind
            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.

            Path parameters

            • invoice_id

              string

              required

              The ID of the invoice for which to send a reminder.

            Request body

            • subject

              string

              The subject of the email that is sent as a notification to the recipient.

              Maximum length: 4000.

            • note

              string

              A note to the payer.

              Maximum length: 4000.

            • send_to_invoicer

              boolean

              Indicates whether to send a copy of the email to the merchant.

            • send_to_recipient

              boolean

              Indicates whether to send a copy of the email to the recipient.

            • additional_recipients

              array (contains the email_address object)

              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.

            Sample Request

            curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/remind \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "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"
  ]
}'

            Response

            A successful request returns the HTTP 204 No Content status code with no JSON response body.

              Sample Response

              204 No Content

              Send invoice

              POST/v2/invoicing/invoices/{invoice_id}/send
              Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:
              • If the invoice issue date is current or in the past, sends the invoice immediately.
              • If the invoice issue date is in the future, schedules the invoice to be sent on that 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:
              • After you send an invoice, resending it has no effect.
              • To send a notification for updates, update the invoice and set the send_to_recipient body parameter to true.

              Path parameters

              • invoice_id

                string

                required

                The ID of the invoice to send.

              Request body

              • subject

                string

                The subject of the email that is sent as a notification to the recipient.

                Maximum length: 4000.

              • note

                string

                A note to the payer.

                Maximum length: 4000.

              • send_to_invoicer

                boolean

                Indicates whether to send a copy of the email to the merchant.

              • send_to_recipient

                boolean

                Indicates whether to send a copy of the email to the recipient.

              • additional_recipients

                array (contains the email_address object)

                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.

              Sample Request

              curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: b1d1f06c7246c" \
-d '{
  "send_to_invoicer": true
}'

              Response

              A successful request returns the HTTP 202 Accepted status code with no JSON response body, when the invoice issue date is in future.

              Sample Response

              202 Accepted

              Search invoices (resource group)

              Use the /search-invoices resource to search for and list invoices that match search criteria.

              Search for invoices

              POST/v2/invoicing/search-invoices
              Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.

              Query parameters

              • page

                integer

                The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.

                Minimum value: 1.

                Maximum value: 1000.

              • page_size

                integer

                The page size for the search results.

                Minimum value: 1.

                Maximum value: 100.

              • total_required

                boolean

                Indicates whether the to show total_pages and total_items in the response.

              Request body

              • recipient_email

                string

                Filters the search by the email address.

                Maximum length: 254.

              • recipient_first_name

                string

                Filters the search by the recipient first name.

                Maximum length: 140.

              • recipient_last_name

                string

                Filters the search by the recipient last name.

                Maximum length: 140.

              • recipient_business_name

                string

                Filters the search by the recipient business name.

                Maximum length: 300.

              • invoice_number

                string

                Filters the search by the invoice number.

                Maximum length: 25.

              • status

                array (contains the invoice_status object)

                An array of status values.

              • reference

                string

                The reference data, such as a PO number.

                Maximum length: 120.

              • currency_code

                string

                The three-character ISO-4217 currency code that identifies the currency.

              • memo

                string

                A private bookkeeping memo for the user.

                Maximum length: 500.

              • total_amount_range

                object

                Filters the search by the total amount.

              • invoice_date_range

                object

                Filters the search by a date range for the invoice, in Internet date and time format.

              • due_date_range

                object

                Filters the search by a due date range for the invoice, in Internet date and time format.

              • payment_date_range

                object

                The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

              • creation_date_range

                object

                Filters the search by a creation date range for the invoice, in Internet date and time format.

              • archived

                boolean

                Indicates whether to list merchant-archived invoices in the response. Value is:

                • true. Response lists only merchant-archived invoices.
                • false. Response lists only unarchived invoices.
                • null. Response lists all invoices.

              • fields

                array (contains the field object)

                A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are items, payments, refunds, additional_recipients_info, and attachments.

              Sample Request

              curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/search-invoices?page=1&page_size=1&total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "total_amount_range": {
    "lower_amount": {
      "currency_code": "USD",
      "value": "50.00"
    },
    "upper_amount": {
      "currency_code": "USD",
      "value": "50.00"
    }
  },
  "invoice_date_range": {
    "start": "2018-06-01",
    "end": "2018-06-21"
  }
}'

              Response

              A successful request returns the HTTP 200 OK status code and a JSON response body that lists the invoices that match the search criteria.
              • total_pages

                integer

                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

                Read only.

              • total_items

                integer

                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.

                Read only.

              • items

                array (contains the invoice object)

                The list of invoices that match the search criteria.

                Read only.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              Sample Response

              {
  "total_items": 6,
  "total_pages": 1,
  "items": [
    {
      "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
      "status": "DRAFT",
      "detail": {
        "invoice_number": "#123",
        "reference": "deal-ref",
        "invoice_date": "2018-11-12",
        "currency_code": "USD",
        "note": "Thank you for your business.",
        "term": "No refunds after 30 days.",
        "memo": "This is a long contract",
        "payment_term": {
          "term_type": "NET_10",
          "due_date": "2018-11-22"
        },
        "metadata": {
          "create_time": "2018-11-12T08:00:20Z",
          "recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",
          "invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"
        }
      },
      "invoicer": {
        "email_address": "merchant@example.com"
      },
      "primary_recipients": [
        {
          "billing_info": {
            "email_address": "bill-me@example.com"
          }
        }
      ],
      "amount": {
        "currency_code": "USD",
        "value": "74.21"
      },
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/invoices?page=2&page_size=10&total_required=true",
      "rel": "next",
      "method": "POST"
    }
  ]
}

              Templates (resource group)

              Use the /templates resource to create, list, show details for, update, and delete invoice templates. Use the /templates resource when you create a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.

              Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. When you create an invoice, you can use the URI for that logo.

              List templates

              GET/v2/invoicing/templates
              Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.
              The user can select which values to show in the business information section of their template.

              Query parameters

              • fields

                string

                The fields to return in the response. Value is all or none. To return only the template name, ID, and default attributes, specify none.

                Pattern: (?i)^(all|none)$.

              • page

                integer

                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.

                Minimum value: 1.

                Maximum value: 1000.

              • page_size

                integer

                The maximum number of templates to return in the response.

                Minimum value: 1.

                Maximum value: 100.

              Sample Request

              curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

              Response

              A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices.
              • addresses

                array (contains the address_portable object)

                An array of addresses in the user's PayPal profile.

                Read only.

              • emails

                string

                An array of emails in the user's PayPal profile.

                Read only.

              • phones

                array (contains the phone_detail object)

                An array of phone numbers in the user's PayPal profile.

              • templates

                array (contains the template object)

                An array of details for each template. If fields is none, returns only the template name, ID, and default status.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              Sample Response

              {
  "addresses": [
    {
      "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"
    },
    {
      "address_line_1": "26303 E 8216 N",
      "address_line_2": "045608 Ocean Bay Plaza #02",
      "admin_area_2": "Garden City",
      "admin_area_1": "NY",
      "postal_code": "11530",
      "country_code": "US"
    }
  ],
  "emails": "email@example.com, email2@example.com",
  "phones": [
    {
      "country_code": "001",
      "national_number": "4085551234",
      "phone_type": "HOME"
    },
    {
      "country_code": "1",
      "national_number": "3477832250",
      "phone_type": "MOBILE"
    },
    {
      "country_code": "1",
      "national_number": "3479543267",
      "phone_type": "FAX"
    },
    {
      "country_code": "1",
      "national_number": "7183514942",
      "phone_type": "OTHER"
    }
  ],
  "templates": [
    {
      "id": "TEMP-19V05281TU309413B",
      "name": "reference-temp",
      "default_template": true,
      "template_info": {
        "configuration": {
          "tax_calculated_after_discount": true,
          "tax_inclusive": false,
          "allow_tip": true,
          "partial_payment": {
            "allow_partial_payment": true,
            "minimum_amount_due": {
              "currency_code": "USD",
              "value": "20.00"
            }
          }
        },
        "detail": {
          "reference": "deal-ref",
          "currency_code": "USD",
          "note": "Thank you for your business.",
          "terms_and_conditions": "No refunds after 30 days.",
          "memo": "This is a long contract",
          "attachments": [
            {
              "id": "Screen Shot 2018-11-23 at 16.45.01.png",
              "reference_url": "https://exxample.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
            }
          ],
          "payment_term": {
            "term_type": "NET_10"
          },
          "metadata": {
            "create_time": "2018-12-03T03:38:46z"
          }
        },
        "invoicer": {
          "name": {
            "given_name": "David",
            "surname": "Larusso"
          },
          "address": {
            "address_line_1": "1234 First Street",
            "address_line_2": "337673 Hillside Court",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "merchant@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4085551234",
              "phone_type": "MOBILE"
            }
          ],
          "website": "www.test.com",
          "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
          "logo_url": "https://example.com/logo.PNG",
          "additional_notes": "2-4"
        },
        "primary_recipients": [
          {
            "billing_info": {
              "name": {
                "given_name": "Stephanie",
                "surname": "Meyers"
              },
              "address": {
                "address_line_1": "1234 Main Street",
                "admin_area_2": "Anytown",
                "admin_area_1": "CA",
                "postal_code": "98765",
                "country_code": "US"
              },
              "email_address": "bill-me@example.com",
              "phones": [
                {
                  "country_code": "001",
                  "national_number": "4884551234",
                  "phone_type": "MOBILE"
                }
              ],
              "additional_info": "add-info"
            },
            "shipping_info": {
              "name": {
                "given_name": "Stephanie",
                "surname": "Meyers"
              },
              "address": {
                "address_line_1": "1234 Main Street",
                "admin_area_2": "Anytown",
                "admin_area_1": "CA",
                "postal_code": "98765",
                "country_code": "US"
              }
            }
          }
        ],
        "additional_recipients": [
          "inform-me@example.com"
        ],
        "items": [
          {
            "id": "ITEM-9R873787D1610780X",
            "name": "Yoga Mat",
            "description": "new watch",
            "quantity": "1",
            "unit_amount": {
              "currency_code": "USD",
              "value": "50.00"
            },
            "tax": {
              "id": "TAX-9R873787D1610780X",
              "name": "Sales Tax",
              "percent": "7.25",
              "amount": {
                "currency_code": "USD",
                "value": "3.27"
              }
            },
            "discount": {
              "percent": "5",
              "amount": {
                "currency_code": "USD",
                "value": "2.5"
              }
            },
            "unit_of_measure": "QUANTITY"
          },
          {
            "id": "ITEM-4XD34145EH4061035",
            "name": "Yoga t-shirt",
            "quantity": "1",
            "unit_amount": {
              "currency_code": "USD",
              "value": "10.00"
            },
            "tax": {
              "id": "TAX-4XD34145EH4061035",
              "name": "Sales Tax",
              "percent": "7.25",
              "amount": {
                "currency_code": "USD",
                "value": "0.34"
              }
            },
            "discount": {
              "amount": {
                "currency_code": "USD",
                "value": "5.00"
              }
            },
            "unit_of_measure": "QUANTITY"
          }
        ],
        "amount": {
          "currency_code": "USD",
          "value": "74.21",
          "breakdown": {
            "item_total": {
              "currency_code": "USD",
              "value": "60.00"
            },
            "custom": {
              "label": "Packing Charges",
              "amount": {
                "currency_code": "USD",
                "value": "10.00"
              }
            },
            "shipping": {
              "amount": {
                "currency_code": "USD",
                "value": "10.00"
              },
              "tax": {
                "name": "Sales Tax",
                "percent": "7.25",
                "amount": {
                  "currency_code": "USD",
                  "value": "0.73"
                }
              }
            },
            "discount": {
              "item_discount": {
                "currency_code": "USD",
                "value": "-7.50"
              },
              "invoice_discount": {
                "percent": "5",
                "amount": {
                  "currency_code": "USD",
                  "value": "-2.63"
                }
              }
            },
            "tax_total": {
              "currency_code": "USD",
              "value": "4.34"
            }
          }
        }
      },
      "settings": {
        "template_item_settings": [
          {
            "field_name": "items.date",
            "display_preference": {
              "hidden": true
            }
          },
          {
            "field_name": "items.discount",
            "display_preference": {
              "hidden": false
            }
          },
          {
            "field_name": "items.tax",
            "display_preference": {
              "hidden": false
            }
          },
          {
            "field_name": "items.description",
            "display_preference": {
              "hidden": false
            }
          },
          {
            "field_name": "items.quantity",
            "display_preference": {
              "hidden": true
            }
          }
        ],
        "template_subtotal_settings": [
          {
            "field_name": "custom",
            "display_preference": {
              "hidden": false
            }
          },
          {
            "field_name": "discount",
            "display_preference": {
              "hidden": false
            }
          },
          {
            "field_name": "shipping",
            "display_preference": {
              "hidden": false
            }
          }
        ]
      },
      "unit_of_measure": "QUANTITY",
      "standard_template": false,
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "default_template": true,
      "id": "TEMP-11E67842VH3080617",
      "name": "Quantity",
      "template_info": {
        "invoicer": {
          "name": {
            "given_name": "David",
            "surname": "Larusso"
          },
          "email_address": "bill-me@example.com"
        },
        "detail": {
          "currency_code": "USD"
        }
      },
      "standard_template": false,
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-11E67842VH3080617",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "default_template": false,
      "id": "TEMP-6HC14139B8663074X",
      "name": "Hours",
      "template_info": {
        "invoicer": {
          "name": {
            "given_name": "David",
            "surname": "Larusso"
          },
          "email_address": "bill-me@example.com"
        },
        "detail": {
          "currency_code": "USD"
        }
      },
      "standard_template": false,
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-6HC14139B8663074X",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ]
}

              Create template

              POST/v2/invoicing/templates
              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.

              Request body

              • id

                string

                The ID of the template.

                Maximum length: 30.

              • name

                string

                The template name.

                Note: The template name must be unique.

                Minimum length: 1.

                Maximum length: 500.

              • default_template

                boolean

                Indicates whether this template is the default template. A invoicer can have one default template.

              • template_info

                object

                The template details. Includes invoicer business information, invoice recipients, items, and configuration.

              • settings

                object

                The template settings. Describes which fields to show or hide when you create an invoice.

              • unit_of_measure

                enum

                The unit of measure for the template. Value is quantity, hours, or amount.

                The possible values are:

                • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
              • standard_template

                boolean

                Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

              Sample Request

              curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "default_template": true,
  "template_info": {
    "configuration": {
      "tax_calculated_after_discount": true,
      "tax_inclusive": false,
      "allow_tip": true,
      "partial_payment": {
        "allow_partial_payment": true,
        "minimum_amount_due": {
          "currency_code": "USD",
          "value": "20.00"
        }
      }
    },
    "detail": {
      "reference": "deal-ref",
      "note": "Thank you for your business.",
      "currency_code": "USD",
      "terms_and_conditions": "No refunds after 30 days.",
      "memo": "This is a long contract",
      "attachments": [
        {
          "id": "Screen Shot 2018-11-23 at 16.45.01.png",
          "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
        }
      ],
      "payment_term": {
        "term_type": "NET_10"
      }
    },
    "invoicer": {
      "name": {
        "given_name": "David",
        "surname": "Larusso"
      },
      "address": {
        "address_line_1": "1234 First Street",
        "address_line_2": "337673 Hillside Court",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "98765",
        "country_code": "US"
      },
      "email_address": "merchant@example.com",
      "phones": [
        {
          "country_code": "001",
          "national_number": "4085551234",
          "phone_type": "MOBILE"
        }
      ],
      "website": "www.test.com",
      "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      "logo_url": "https://example.com/logo.PNG",
      "additional_notes": "2-4"
    },
    "primary_recipients": [
      {
        "billing_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "bill-me@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4884551234",
              "phone_type": "MOBILE"
            }
          ],
          "additional_info": "add-info"
        },
        "shipping_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          }
        }
      }
    ],
    "additional_recipients": [
      "inform-me@example.com"
    ],
    "items": [
      {
        "name": "Yoga Mat",
        "description": "new watch",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "50.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        },
        "discount": {
          "percent": "5"
        },
        "unit_of_measure": "QUANTITY"
      },
      {
        "name": "Yoga T Shirt",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        },
        "discount": {
          "amount": {
            "currency_code": "USD",
            "value": "5.00"
          }
        },
        "unit_of_measure": "QUANTITY"
      }
    ],
    "amount": {
      "currency_code": "USD",
      "value": "74.21",
      "breakdown": {
        "custom": {
          "label": "Packing Charges",
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        },
        "shipping": {
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25"
          }
        },
        "discount": {
          "invoice_discount": {
            "percent": "5"
          }
        }
      }
    }
  },
  "settings": {
    "template_item_settings": [
      {
        "field_name": "items.date",
        "display_preference": {
          "hidden": true
        }
      },
      {
        "field_name": "items.discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.tax",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.description",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.quantity",
        "display_preference": {
          "hidden": true
        }
      }
    ],
    "template_subtotal_settings": [
      {
        "field_name": "custom",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "shipping",
        "display_preference": {
          "hidden": false
        }
      }
    ]
  },
  "unit_of_measure": "QUANTITY",
  "standard_template": false
}'

              Response

              A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details if you set prefer=return=representation.
              • href

                string

                The complete target URL. To make the related call, combine the method with this URI Template-formatted 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

                string

                The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

              • method

                enum

                The HTTP method required to make the related call.

                Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

              Sample Response

              {
  "id": "TEMP-19V05281TU309413B",
  "name": "reference-temp",
  "default_template": true,
  "template_info": {
    "configuration": {
      "tax_calculated_after_discount": true,
      "tax_inclusive": false,
      "allow_tip": true,
      "partial_payment": {
        "allow_partial_payment": true,
        "minimum_amount_due": {
          "currency_code": "USD",
          "value": "20.00"
        }
      }
    },
    "detail": {
      "reference": "deal-ref",
      "note": "Thank you for your business.",
      "currency_code": "USD",
      "terms_and_conditions": "No refunds after 30 days.",
      "memo": "This is a long contract",
      "attachments": [
        {
          "id": "Screen Shot 2018-11-23 at 16.45.01.png",
          "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
        }
      ],
      "payment_term": {
        "term_type": "NET_10"
      },
      "metadata": {
        "create_time": "2018-12-03T03:38:46z"
      }
    },
    "invoicer": {
      "name": {
        "given_name": "David",
        "surname": "Larusso"
      },
      "address": {
        "address_line_1": "1234 First Street",
        "address_line_2": "337673 Hillside Court",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "98765",
        "country_code": "US"
      },
      "email_address": "merchant@example.com",
      "phones": [
        {
          "country_code": "001",
          "national_number": "4085551234",
          "phone_type": "MOBILE"
        }
      ],
      "website": "www.test.com",
      "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      "logo_url": "https://example.com/logo.PNG",
      "additional_notes": "2-4"
    },
    "primary_recipients": [
      {
        "billing_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "bill-me@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4884551234",
              "phone_type": "MOBILE"
            }
          ],
          "additional_info": "add-info"
        },
        "shipping_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          }
        }
      }
    ],
    "additional_recipients": [
      "inform-me@example.com"
    ],
    "items": [
      {
        "id": "ITEM-9R873787D1610780X",
        "name": "Yoga Mat",
        "description": "new watch",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "50.00"
        },
        "tax": {
          "id": "TAX-9R873787D1610780X",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "3.27"
          }
        },
        "discount": {
          "percent": "5",
          "amount": {
            "currency_code": "USD",
            "value": "2.5"
          }
        },
        "unit_of_measure": "QUANTITY"
      },
      {
        "id": "ITEM-4XD34145EH4061035",
        "name": "Yoga T Shirt",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "id": "TAX-4XD34145EH4061035",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "0.34"
          }
        },
        "discount": {
          "amount": {
            "currency_code": "USD",
            "value": "5.00"
          }
        },
        "unit_of_measure": "QUANTITY"
      }
    ],
    "amount": {
      "currency_code": "USD",
      "value": "74.21",
      "breakdown": {
        "item_total": {
          "currency_code": "USD",
          "value": "60.00"
        },
        "custom": {
          "label": "Packing Charges",
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        },
        "shipping": {
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25",
            "amount": {
              "currency_code": "USD",
              "value": "0.73"
            }
          }
        },
        "discount": {
          "item_discount": {
            "currency_code": "USD",
            "value": "-7.50"
          },
          "invoice_discount": {
            "percent": "5",
            "amount": {
              "currency_code": "USD",
              "value": "-2.63"
            }
          }
        },
        "tax_total": {
          "currency_code": "USD",
          "value": "4.34"
        }
      }
    }
  },
  "settings": {
    "template_item_settings": [
      {
        "field_name": "items.date",
        "display_preference": {
          "hidden": true
        }
      },
      {
        "field_name": "items.discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.tax",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.description",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.quantity",
        "display_preference": {
          "hidden": true
        }
      }
    ],
    "template_subtotal_settings": [
      {
        "field_name": "custom",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "shipping",
        "display_preference": {
          "hidden": false
        }
      }
    ]
  },
  "unit_of_measure": "QUANTITY",
  "standard_template": false,
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}

              Delete template

              DELETE/v2/invoicing/templates/{template_id}
              Deletes a template, by ID.

              Path parameters

              • template_id

                string

                required

                The ID of the template to delete.

              Sample Request

              curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

              Response

              A successful request returns the HTTP 204 No Content status code with no JSON response body.

                Sample Response

                204 No Content

                Fully update template

                PUT/v2/invoicing/templates/{template_id}
                Fully updates a template, by ID. In the JSON request body, include a complete template object. This call does not support partial updates.

                Path parameters

                • template_id

                  string

                  required

                  The ID of the template for which to show details.

                Request body

                • id

                  string

                  The ID of the template.

                  Maximum length: 30.

                • name

                  string

                  The template name.

                  Note: The template name must be unique.

                  Minimum length: 1.

                  Maximum length: 500.

                • default_template

                  boolean

                  Indicates whether this template is the default template. A invoicer can have one default template.

                • template_info

                  object

                  The template details. Includes invoicer business information, invoice recipients, items, and configuration.

                • settings

                  object

                  The template settings. Describes which fields to show or hide when you create an invoice.

                • unit_of_measure

                  enum

                  The unit of measure for the template. Value is quantity, hours, or amount.

                  The possible values are:

                  • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                  • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                  • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
                • standard_template

                  boolean

                  Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.

                • links

                  array (contains the link_description object)

                  An array of request-related HATEOAS links.

                Sample Request

                curl -v -X PUT https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "default_template": true,
  "template_info": {
    "configuration": {
      "tax_calculated_after_discount": true,
      "tax_inclusive": false,
      "allow_tip": true,
      "partial_payment": {
        "allow_partial_payment": true,
        "minimum_amount_due": {
          "currency_code": "USD",
          "value": "20.00"
        }
      }
    },
    "detail": {
      "reference": "deal-reference-value",
      "note": "Thank you for your business.",
      "currency_code": "USD",
      "terms_and_conditions": "No refunds after 30 days.",
      "memo": "This is a long contract",
      "attachments": [
        {
          "id": "Screen Shot 2018-11-23 at 16.45.01.png",
          "reference_url": "https://example.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
        }
      ],
      "payment_term": {
        "term_type": "NET_10"
      }
    },
    "invoicer": {
      "name": {
        "given_name": "David",
        "surname": "Larusso"
      },
      "address": {
        "address_line_1": "1234 First Street",
        "address_line_2": "337673 Hillside Court",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "98765",
        "country_code": "US"
      },
      "email_address": "merchant@example.com",
      "phones": [
        {
          "country_code": "001",
          "national_number": "4085551234",
          "phone_type": "MOBILE"
        }
      ],
      "website": "www.test.com",
      "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      "logo_url": "https://example.com/logo.PNG",
      "additional_notes": "2-4"
    },
    "primary_recipients": [
      {
        "billing_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "bill-me@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4884551234",
              "phone_type": "MOBILE"
            }
          ],
          "additional_info": "add-info"
        },
        "shipping_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          }
        }
      }
    ],
    "additional_recipients": [
      "inform-me@example.com"
    ],
    "items": [
      {
        "name": "Yoga Mat",
        "description": "new watch",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "50.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        },
        "discount": {
          "percent": "5"
        },
        "unit_of_measure": "QUANTITY"
      },
      {
        "name": "Yoga T Shirt",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        },
        "discount": {
          "amount": {
            "currency_code": "USD",
            "value": "5.00"
          }
        },
        "unit_of_measure": "QUANTITY"
      }
    ],
    "amount": {
      "currency_code": "USD",
      "value": "74.21",
      "breakdown": {
        "custom": {
          "label": "Packing Charges",
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        },
        "shipping": {
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25"
          }
        },
        "discount": {
          "invoice_discount": {
            "percent": "5"
          }
        }
      }
    }
  },
  "settings": {
    "template_item_settings": [
      {
        "field_name": "items.date",
        "display_preference": {
          "hidden": true
        }
      },
      {
        "field_name": "items.discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.tax",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.description",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.quantity",
        "display_preference": {
          "hidden": true
        }
      }
    ],
    "template_subtotal_settings": [
      {
        "field_name": "custom",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "shipping",
        "display_preference": {
          "hidden": false
        }
      }
    ]
  },
  "unit_of_measure": "QUANTITY",
  "standard_template": false
}'

                Response

                A successful request returns the HTTP 204 No Content status code with no JSON response body.
                • id

                  string

                  The ID of the template.

                  Read only.

                  Maximum length: 30.

                • name

                  string

                  The template name.

                  Note: The template name must be unique.

                  Minimum length: 1.

                  Maximum length: 500.

                • default_template

                  boolean

                  Indicates whether this template is the default template. A invoicer can have one default template.

                • template_info

                  object

                  The template details. Includes invoicer business information, invoice recipients, items, and configuration.

                • settings

                  object

                  The template settings. Describes which fields to show or hide when you create an invoice.

                • unit_of_measure

                  enum

                  The unit of measure for the template. Value is quantity, hours, or amount.

                  The possible values are:

                  • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                  • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                  • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
                • standard_template

                  boolean

                  Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.

                  Read only.

                • links

                  array (contains the link_description object)

                  An array of request-related HATEOAS links.

                  Read only.

                Sample Response

                {
  "id": "TEMP-19V05281TU309413B",
  "name": "reference-temp",
  "default_template": true,
  "template_info": {
    "configuration": {
      "tax_calculated_after_discount": true,
      "tax_inclusive": false,
      "allow_tip": true,
      "partial_payment": {
        "allow_partial_payment": true,
        "minimum_amount_due": {
          "currency_code": "USD",
          "value": "20.00"
        }
      }
    },
    "detail": {
      "reference": "deal-reference-value",
      "currency_code": "USD",
      "note": "Thank you for your business.",
      "terms_and_conditions": "No refunds after 30 days.",
      "memo": "This is a long contract",
      "attachments": [
        {
          "id": "Screen Shot 2018-11-23 at 16.45.01.png",
          "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
        }
      ],
      "payment_term": {
        "term_type": "NET_10"
      },
      "metadata": {
        "create_time": "2018-12-03T03:38:46z"
      }
    },
    "invoicer": {
      "name": {
        "given_name": "David",
        "surname": "Larusso"
      },
      "address": {
        "address_line_1": "1234 First Street",
        "address_line_2": "337673 Hillside Court",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "98765",
        "country_code": "US"
      },
      "email_address": "merchant@example.com",
      "phones": [
        {
          "country_code": "001",
          "national_number": "4085551234",
          "phone_type": "MOBILE"
        }
      ],
      "website": "www.test.com",
      "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      "logo_url": "https://example.com/logo.PNG",
      "additional_notes": "2-4"
    },
    "primary_recipients": [
      {
        "billing_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "bill-me@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4884551234",
              "phone_type": "MOBILE"
            }
          ],
          "additional_info": "add-info"
        },
        "shipping_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          }
        }
      }
    ],
    "additional_recipients": [
      "inform-me@example.com"
    ],
    "items": [
      {
        "id": "ITEM-9R873787D1610780X",
        "name": "Yoga Mat",
        "description": "new watch",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "50.00"
        },
        "tax": {
          "id": "TAX-9R873787D1610780X",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "3.27"
          }
        },
        "discount": {
          "percent": "5",
          "amount": {
            "currency_code": "USD",
            "value": "2.5"
          }
        },
        "unit_of_measure": "QUANTITY"
      },
      {
        "id": "ITEM-4XD34145EH4061035",
        "name": "Yoga T Shirt",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "id": "TAX-4XD34145EH4061035",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "0.34"
          }
        },
        "discount": {
          "amount": {
            "currency_code": "USD",
            "value": "5.00"
          }
        },
        "unit_of_measure": "QUANTITY"
      }
    ],
    "amount": {
      "currency_code": "USD",
      "value": "74.21",
      "breakdown": {
        "item_total": {
          "currency_code": "USD",
          "value": "60.00"
        },
        "custom": {
          "label": "Packing Charges",
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        },
        "shipping": {
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25",
            "amount": {
              "currency_code": "USD",
              "value": "0.73"
            }
          }
        },
        "discount": {
          "item_discount": {
            "currency_code": "USD",
            "value": "-7.50"
          },
          "invoice_discount": {
            "percent": "5",
            "amount": {
              "currency_code": "USD",
              "value": "-2.63"
            }
          }
        },
        "tax_total": {
          "currency_code": "USD",
          "value": "4.34"
        }
      }
    }
  },
  "settings": {
    "template_item_settings": [
      {
        "field_name": "items.date",
        "display_preference": {
          "hidden": true
        }
      },
      {
        "field_name": "items.discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.tax",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.description",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.quantity",
        "display_preference": {
          "hidden": true
        }
      }
    ],
    "template_subtotal_settings": [
      {
        "field_name": "custom",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "shipping",
        "display_preference": {
          "hidden": false
        }
      }
    ]
  },
  "unit_of_measure": "QUANTITY",
  "standard_template": false,
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}

                Show template details

                GET/v2/invoicing/templates/{template_id}
                Shows details for a template, by ID.

                Path parameters

                • template_id

                  string

                  required

                  The ID of the template for which to show details.

                Sample Request

                curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

                Response

                A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details.
                • id

                  string

                  The ID of the template.

                  Read only.

                  Maximum length: 30.

                • name

                  string

                  The template name.

                  Note: The template name must be unique.

                  Minimum length: 1.

                  Maximum length: 500.

                • default_template

                  boolean

                  Indicates whether this template is the default template. A invoicer can have one default template.

                • template_info

                  object

                  The template details. Includes invoicer business information, invoice recipients, items, and configuration.

                • settings

                  object

                  The template settings. Describes which fields to show or hide when you create an invoice.

                • unit_of_measure

                  enum

                  The unit of measure for the template. Value is quantity, hours, or amount.

                  The possible values are:

                  • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                  • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                  • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
                • standard_template

                  boolean

                  Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.

                  Read only.

                • links

                  array (contains the link_description object)

                  An array of request-related HATEOAS links.

                  Read only.

                Sample Response

                {
  "id": "TEMP-19V05281TU309413B",
  "name": "reference-temp",
  "default_template": true,
  "template_info": {
    "configuration": {
      "tax_calculated_after_discount": true,
      "tax_inclusive": false,
      "allow_tip": true,
      "partial_payment": {
        "allow_partial_payment": true,
        "minimum_amount_due": {
          "currency_code": "USD",
          "value": "20.00"
        }
      }
    },
    "detail": {
      "reference": "deal-ref",
      "currency_code": "USD",
      "note": "Thank you for your business.",
      "terms_and_conditions": "No refunds after 30 days.",
      "memo": "This is a long contract",
      "attachments": [
        {
          "id": "Screen Shot 2018-11-23 at 16.45.01.png",
          "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
        }
      ],
      "payment_term": {
        "term_type": "NET_10"
      },
      "metadata": {
        "create_time": "2018-12-03T03:38:46z"
      }
    },
    "invoicer": {
      "name": {
        "given_name": "David",
        "surname": "Larusso"
      },
      "address": {
        "address_line_1": "1234 First Street",
        "address_line_2": "337673 Hillside Court",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "98765",
        "country_code": "US"
      },
      "email_address": "merchant@example.com",
      "phones": [
        {
          "country_code": "001",
          "national_number": "4085551234",
          "phone_type": "MOBILE"
        }
      ],
      "website": "www.test.com",
      "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      "logo_url": "https://example.com/logo.PNG",
      "additional_notes": "2-4"
    },
    "primary_recipients": [
      {
        "billing_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          },
          "email_address": "bill-me@example.com",
          "phones": [
            {
              "country_code": "001",
              "national_number": "4884551234",
              "phone_type": "MOBILE"
            }
          ],
          "additional_info": "add-info"
        },
        "shipping_info": {
          "name": {
            "given_name": "Stephanie",
            "surname": "Meyers"
          },
          "address": {
            "address_line_1": "1234 Main Street",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "98765",
            "country_code": "US"
          }
        }
      }
    ],
    "additional_recipients": [
      "inform-me@example.com"
    ],
    "items": [
      {
        "id": "ITEM-9R873787D1610780X",
        "name": "Yoga Mat",
        "description": "new watch",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "50.00"
        },
        "tax": {
          "id": "TAX-9R873787D1610780X",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "3.27"
          }
        },
        "discount": {
          "percent": "5",
          "amount": {
            "currency_code": "USD",
            "value": "2.5"
          }
        },
        "unit_of_measure": "QUANTITY"
      },
      {
        "id": "ITEM-4XD34145EH4061035",
        "name": "Yoga T Shirt",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "id": "TAX-4XD34145EH4061035",
          "name": "Sales Tax",
          "percent": "7.25",
          "amount": {
            "currency_code": "USD",
            "value": "0.34"
          }
        },
        "discount": {
          "amount": {
            "currency_code": "USD",
            "value": "5.00"
          }
        },
        "unit_of_measure": "QUANTITY"
      }
    ],
    "amount": {
      "currency_code": "USD",
      "value": "74.21",
      "breakdown": {
        "item_total": {
          "currency_code": "USD",
          "value": "60.00"
        },
        "custom": {
          "label": "Packing Charges",
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        },
        "shipping": {
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25",
            "amount": {
              "currency_code": "USD",
              "value": "0.73"
            }
          }
        },
        "discount": {
          "item_discount": {
            "currency_code": "USD",
            "value": "-7.50"
          },
          "invoice_discount": {
            "percent": "5",
            "amount": {
              "currency_code": "USD",
              "value": "-2.63"
            }
          }
        },
        "tax_total": {
          "currency_code": "USD",
          "value": "4.34"
        }
      }
    }
  },
  "settings": {
    "template_item_settings": [
      {
        "field_name": "items.date",
        "display_preference": {
          "hidden": true
        }
      },
      {
        "field_name": "items.discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.tax",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.description",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "items.quantity",
        "display_preference": {
          "hidden": true
        }
      }
    ],
    "template_subtotal_settings": [
      {
        "field_name": "custom",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "discount",
        "display_preference": {
          "hidden": false
        }
      },
      {
        "field_name": "shipping",
        "display_preference": {
          "hidden": false
        }
      }
    ]
  },
  "unit_of_measure": "QUANTITY",
  "standard_template": false,
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}

                Common object definitions

                202_response

                address_details

                • street_number

                  string

                  The street number.

                  Maximum length: 100.

                • street_name

                  string

                  The street name. Just Drury in Drury Lane.

                  Maximum length: 100.

                • street_type

                  string

                  The street type. For example, avenue, boulevard, road, or expressway.

                  Maximum length: 100.

                • delivery_service

                  string

                  The delivery service. Post office box, bag number, or post office name.

                  Maximum length: 100.

                • building_name

                  string

                  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.

                  Maximum length: 100.

                • sub_building

                  string

                  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.

                  Maximum length: 100.

                address_portable

                • address_line_1

                  string

                  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.

                  Maximum length: 300.

                • address_line_2

                  string

                  The second line of the address. For example, suite or apartment number.

                  Maximum length: 300.

                • address_line_3

                  string

                  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.

                  Maximum length: 100.

                • admin_area_4

                  string

                  The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:

                  • The postal sorting code for Guernsey and many French territories, such as French Guiana.
                  • The fine-grained administrative levels in China.

                  Maximum length: 100.

                • admin_area_3

                  string

                  A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:

                  • Brazil. Suburb, bairro, or neighborhood.
                  • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

                  Maximum length: 100.

                • admin_area_2

                  string

                  A city, town, or village. Smaller than admin_area_level_1.

                  Maximum length: 120.

                • admin_area_1

                  string

                  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:

                  • UK. A county.
                  • US. A state.
                  • Canada. A province.
                  • Japan. A prefecture.
                  • Switzerland. A kanton.

                  Maximum length: 300.

                • postal_code

                  string

                  The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

                  Maximum length: 60.

                • country_code

                  string

                  required

                  The two-character ISO 3166-1 code 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.

                  Minimum length: 2.

                  Maximum length: 2.

                  Pattern: ^([A-Z]{2}|C2)$.

                • address_details

                  object

                  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.

                address_portable_postal_code_validation

                • address_portable_postal_code_validation

                aggregated_discount

                • invoice_discount

                  object

                  The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.

                • item_discount

                  object

                  The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount.

                amount_range

                • lower_amount

                  object

                  required

                  The lower limit of the amount range.

                • upper_amount

                  object

                  required

                  The upper limit of the amount range.

                amount_summary_detail

                • currency_code

                  string

                  The three-character ISO-4217 currency code that identifies the currency.

                • value

                  string

                  The value, which might be:

                  • An integer for currencies like JPY that are not typically fractional.
                  • A decimal fraction for currencies like TND that are subdivided into thousandths.
                  For the required number of decimal places for a currency code, see Currency Codes.

                  Maximum length: 32.

                  Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

                • breakdown

                  object

                  The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any.

                amount_with_breakdown

                • item_total

                  object

                  The subtotal for all items. Must equal the sum of (items[].unit_amount * items[].quantity) for all items.

                • discount

                  object

                  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

                  object

                  The aggregated amount of the item and shipping taxes.

                • shipping

                  object

                  The shipping fee for all items. Includes tax on shipping.

                • custom

                  object

                  The custom amount to apply to an invoice. If you include a label, you must include the custom amount.

                billing_info

                  • email_address

                    string

                    The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.

                  • phones

                    array (contains the phone_detail object)

                    The invoice recipient's phone numbers. Extension number is not supported.

                  • additional_info

                    string

                    Any additional information about the recipient.

                    Maximum length: 40.

                  • language

                    string

                    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.

                    Minimum length: 2.

                    Maximum length: 10.

                    Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.

                  business_name

                  • business_name

                    string

                    Required. The business name of the party.

                    Maximum length: 300.

                  business_name_validation

                  • business_name_validation

                  configuration

                  • tax_calculated_after_discount

                    boolean

                    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.

                  • tax_inclusive

                    boolean

                    Indicates whether the unit price includes tax.

                  • allow_tip

                    boolean

                    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.

                  • partial_payment

                    object

                    The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.

                  • template_id

                    string

                    The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.

                    Maximum length: 30.

                  contact_information

                  • business_name

                    string

                    Required. The business name of the party.

                    Maximum length: 300.

                  • name

                    object

                    The first and Last name of the recipient.

                  • address

                    object

                    The address of the recipient.

                  country_code

                  • country_code

                    string

                    The two-character ISO 3166-1 code 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.

                    Minimum length: 2.

                    Maximum length: 2.

                    Pattern: ^([A-Z]{2}|C2)$.

                  currency_code

                  custom_amount

                  • label

                    string

                    required

                    The label to the custom amount of the invoice.

                    Maximum length: 50.

                  • amount

                    object

                    The custom amount value. Value is from -1000000 to 1000000. Supports up to two decimal places.

                  date_no_time

                  • date_no_time

                    string

                    The stand-alone date, in Internet date and time format. 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.

                    Minimum length: 10.

                    Maximum length: 10.

                    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

                  date_range

                  • start

                    string

                    required

                    The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date.

                  • end

                    string

                    required

                    The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date.

                  date_time

                  • date_time

                    string

                    The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

                    Note: The regular expression provides guidance but does not reject all invalid dates.

                    Minimum length: 20.

                    Maximum length: 64.

                    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

                  date_time_range

                  • start

                    string

                    required

                    The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date.

                  • end

                    string

                    required

                    The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date.

                    Note: The regular expression provides guidance but does not reject all invalid dates.

                    Minimum length: 20.
                    Maximum length: 64
                    Pattern: ^0-9{4}-(01-9|10-2)-(01-9|1-2|30-1)T,t:0-5:(0-5|60)(.+)?(Zz|+-{2}:0-9{2})$

                  detail

                  • reference

                    string

                    The reference data. Includes a post office (PO) number.

                    Maximum length: 120.

                  • currency_code

                    string

                    required

                    The three-character ISO-4217 currency code that identifies the currency.

                    Minimum length: 3.

                    Maximum length: 3.

                  • note

                    string

                    A note to the invoice recipient. Also appears on the invoice notification email.

                    Maximum length: 4000.

                  • terms_and_conditions

                    string

                    The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

                    Maximum length: 4000.

                  • memo

                    string

                    A private bookkeeping memo for the user.

                    Maximum length: 500.

                  • attachments

                    array (contains the file_reference object)

                    An array of PayPal IDs for the files that are attached to an invoice.

                    Maximum value: 5.

                  discount

                  • percent

                    string

                    The discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.

                  • amount

                    object

                    The invoice level discount amount. Value is from 0 to 1000000. Supports up to two decimal places.

                  email_address

                  • email_address

                    string

                    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.

                    Minimum length: 3.

                    Maximum length: 254.

                    Pattern: ^.+@[^"\-].+$.

                  error

                  • name

                    string

                    required

                    The human-readable, unique name of the error.

                  • message

                    string

                    required

                    The message that describes the error.

                  • debug_id

                    string

                    required

                    The PayPal internal ID. Used for correlation purposes.

                  • information_link

                    string

                    The information link, or URI, that shows detailed information about this error for the developer.

                    Read only.

                  • details

                    array (contains the error_details object)

                    An array of additional details about the error.

                  • links

                    array (contains the link_description object)

                    An array of request-related HATEOAS links.

                    Read only.

                  error_details

                  • field

                    string

                    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

                    string

                    The value of the field that caused the error.

                  • location

                    string

                    The location of the field that caused the error. Value is body, path, or query.

                  • issue

                    string

                    required

                    The unique, fine-grained application-level error code.

                  • description

                    string

                    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.

                  field

                  • field

                    string

                    The name of the field.

                  file_reference

                  • id

                    string

                    The ID of the referenced file.

                    Minimum length: 1.

                    Maximum length: 255.

                  • reference_url

                    string

                    The reference URL for the file.

                    Minimum length: 1.

                    Maximum length: 2000.

                  • content_type

                    string

                    The Internet Assigned Numbers Authority (IANA) media type of the file.

                  • create_time

                    string

                    The date and time when the file was created, in Internet date and time format.

                    Minimum length: 20.

                    Maximum length: 64.

                    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

                  • size

                    string

                    The size of the file, in bytes.

                    Pattern: ^[0-9]+$.

                  invoice

                  • id

                    string

                    The ID of the invoice.

                    Read only.

                    Maximum length: 30.

                  • parent_id

                    string

                    The parent ID to an invoice that defines the group invoice to which the invoice is related.

                    Read only.

                    Maximum length: 30.

                  • status

                    enum

                    The status of the invoice.

                    The possible values are:

                    • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
                    • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
                    • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
                    • PAID. The payer has paid for the invoice.
                    • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
                    • CANCELLED. The invoice has been cancelled by the invoicer.
                    • REFUNDED. The invoice has been refunded by the invoicer.
                    • PARTIALLY_PAID. The payer has partially paid for the invoice.
                    • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
                    • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
                    • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
                    • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.

                    Read only.

                  • detail

                    object

                    required

                    The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

                  • invoicer

                    object

                    The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

                  • primary_recipients

                    array (contains the recipient_info object)

                    The billing and shipping information. Includes name, email, address, phone and language.

                  • additional_recipients

                    array (contains the email_address object)

                    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

                    array (contains the item object)

                    An array of invoice line item information.

                  • configuration

                    object

                    The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

                  • amount

                    object

                    The invoice amount summary of item total, discount, tax total and shipping..

                  • due_amount

                    object

                    The due amount, which is the balance amount outstanding after payments.

                    Read only.

                  • gratuity

                    object

                    The amount paid by the payer as gratuity to the invoicer.

                    Read only.

                  • payments

                    object

                    List of payments registered against the invoice..

                  • refunds

                    object

                    List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

                  • links

                    array (contains the link_description object)

                    An array of request-related HATEOAS links.

                    Read only.

                  invoice_creation_flow

                  • invoice_creation_flow

                    enum

                    The frequency at which the invoice is sent:

                    • Multiple recipient. Sent to multiple recipients.
                    • Batch. Sent in a batch.
                    • Regular single. Sent one time to a single recipient.

                    The possible values are:

                    • MULTIPLE_RECIPIENTS_GROUP. The invoice sent to multiple recipients.
                    • BATCH. The invoice sent as a batch.
                    • REGULAR_SINGLE. The regular invoice sent to single recipient.

                  invoice_detail

                  • reference

                    string

                    The reference data. Includes a post office (PO) number.

                    Maximum length: 120.

                  • currency_code

                    string

                    required

                    The three-character ISO-4217 currency code that identifies the currency.

                    Minimum length: 3.

                    Maximum length: 3.

                  • note

                    string

                    A note to the invoice recipient. Also appears on the invoice notification email.

                    Maximum length: 4000.

                  • terms_and_conditions

                    string

                    The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

                    Maximum length: 4000.

                  • memo

                    string

                    A private bookkeeping memo for the user.

                    Maximum length: 500.

                  • attachments

                    array (contains the file_reference object)

                    An array of PayPal IDs for the files that are attached to an invoice.

                  • invoice_number

                    string

                    The invoice number. Default is the number that is auto-incremented number from the last number.

                    Maximum length: 127.

                  • invoice_date

                    string

                    The invoice date as specificed by the sender, in Internet date and time format. Only UTC is supported in response. For example, yyyy-MM-ddTz.

                    Minimum length: 10.

                    Maximum length: 10.

                    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

                  • payment_term

                    object

                    The payment due date for the invoice. Value is either but not both term_type or due_date.

                  • metadata

                    object

                    The audit metadata. Captures all invoicing actions on create, send, update, and cancel.

                  invoice_number

                  • invoice_number

                    string

                    The invoice number. If you omit this value, the default is the auto-incremented number from the last number.

                    Read only.

                    Maximum length: 25.

                  invoice_payment_term

                  • term_type

                    string

                    The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.

                  invoice_status

                  • invoice_status

                    enum

                    The status of the invoice.

                    The possible values are:

                    • DRAFT. The invoice is in draft state. It is not yet sent to the payer.
                    • SENT. The invoice has been sent to the payer. The payment is awaited from the payer.
                    • SCHEDULED. The invoice is scheduled on a future date. It is not yet sent to the payer.
                    • PAID. The payer has paid for the invoice.
                    • MARKED_AS_PAID. The invoice is marked as paid by the invoicer.
                    • CANCELLED. The invoice has been cancelled by the invoicer.
                    • REFUNDED. The invoice has been refunded by the invoicer.
                    • PARTIALLY_PAID. The payer has partially paid for the invoice.
                    • PARTIALLY_REFUNDED. The invoice has been partially refunded by the invoicer.
                    • MARKED_AS_REFUNDED. The invoice is marked as refunded by the invoicer.
                    • UNPAID. The invoicer is yet to receive the payment from the payer for the invoice.
                    • PAYMENT_PENDING. The invoicer is yet to receive the payment for the invoice. It is under pending review.

                  invoicer_info

                    • email_address

                      string

                      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.

                      Minimum length: 3.

                      Maximum length: 254.

                      Pattern: ^.+@[^"\-].+$.

                    • phones

                      array (contains the phone_detail object)

                      An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.

                    • website

                      string

                      The invoicer's website.

                      Maximum length: 2048.

                    • tax_id

                      string

                      The invoicer's tax ID.

                      Maximum length: 100.

                    • additional_notes

                      string

                      Any additional information. Includes business hours.

                      Maximum length: 400.

                    • logo_url

                      string

                      The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.

                      Maximum length: 2000.

                    invoices

                    • total_pages

                      integer

                      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

                      Read only.

                    • total_items

                      integer

                      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.

                      Read only.

                    • items

                      array (contains the invoice object)

                      The list of invoices that match the search criteria.

                      Read only.

                    • links

                      array (contains the link_description object)

                      An array of request-related HATEOAS links.

                      Read only.

                    item

                    • id

                      string

                      The ID of the invoice line item.

                      Read only.

                      Maximum length: 22.

                    • name

                      string

                      required

                      The item name for the invoice line item.

                      Maximum length: 200.

                    • description

                      string

                      The item description for the invoice line item.

                      Maximum length: 1000.

                    • quantity

                      string

                      required

                      The quantity of the item that the invoicer provides to the payer. Value is from -1000000 to 1000000. Supports up to five decimal places.

                      Maximum length: 14.

                    • unit_amount

                      object

                      required

                      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

                      object

                      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

                      string

                      The date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-ddTz.

                    • discount

                      object

                      Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.

                    • unit_of_measure

                      enum

                      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.

                      The possible values are:

                      • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                      • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                      • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.

                    language

                    metadata

                    • create_time

                      string

                      The date and time when the resource was created, in Internet date and time format.

                    • created_by

                      string

                      The email address of the account that created the resource.

                    • last_update_time

                      string

                      The date and time when the resource was last edited, in Internet date and time format.

                    • last_updated_by

                      string

                      The email address of the account that last edited the resource.

                    • cancel_time

                      string

                      The date and time when the resource was canceled, in Internet date and time format.

                    • cancelled_by

                      string

                      The actor who canceled the resource.

                    • first_sent_time

                      string

                      The date and time when the resource was first sent, in Internet date and time format.

                    • last_sent_time

                      string

                      The date and time when the resource was last sent, in Internet date and time format.

                    • last_sent_by

                      string

                      The email address of the account that last sent the resource.

                    • created_by_flow

                      string

                      The flow variation that created this invoice.

                    • recipient_view_url

                      string

                      The URL for the invoice payer view hosted on paypal.com.

                    • invoicer_view_url

                      string

                      The URL for the invoice merchant view hosted on paypal.com.

                    money

                    • currency_code

                      string

                      required

                      The three-character ISO-4217 currency code that identifies the currency.

                    • value

                      string

                      required

                      The value, which might be:

                      • An integer for currencies like JPY that are not typically fractional.
                      • A decimal fraction for currencies like TND that are subdivided into thousandths.
                      For the required number of decimal places for a currency code, see Currency Codes.

                      Maximum length: 32.

                      Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

                    name

                    • prefix

                      string

                      The prefix, or title, to the party's name.

                      Maximum length: 140.

                    • given_name

                      string

                      When the party is a person, the party's given, or first, name.

                      Maximum length: 140.

                    • surname

                      string

                      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.

                      Maximum length: 140.

                    • middle_name

                      string

                      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.

                      Maximum length: 140.

                    • suffix

                      string

                      The suffix for the party's name.

                      Maximum length: 140.

                    • alternate_full_name

                      string

                      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.

                      Maximum length: 300.

                    • full_name

                      string

                      When the party is a person, the party's full name.

                      Maximum length: 300.

                    name_validation

                    • name_validation

                    notification

                    • subject

                      string

                      The subject of the email that is sent as a notification to the recipient.

                      Maximum length: 4000.

                    • note

                      string

                      A note to the payer.

                      Maximum length: 4000.

                    • send_to_invoicer

                      boolean

                      Indicates whether to send a copy of the email to the merchant.

                    • send_to_recipient

                      boolean

                      Indicates whether to send a copy of the email to the recipient.

                    • additional_recipients

                      array (contains the email_address object)

                      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.

                    partial_payment

                    • allow_partial_payment

                      boolean

                      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.

                    • minimum_amount_due

                      object

                      The minimum amount allowed for a partial payment. Valid only when allow_partial_payment is true.

                    payment_detail

                    • type

                      enum

                      The payment type in an invoicing flow which can be PayPal or an external cash or check payment.

                      The possible values are:

                      • PAYPAL. The payment type is PayPal.
                      • EXTERNAL. The payment type is an external cash or a check payment.

                      Read only.

                    • payment_id

                      string

                      The ID for a PayPal payment transaction. Required for the PAYPAL payment type.

                      Maximum length: 22.

                    • payment_date

                      string

                      The date when the invoice was paid, in Internet date and time format. For example, yyyy-MM-dd z.

                    • method

                      enum

                      required

                      The payment mode or method through which the invoicer can accept the payment.

                      The possible values are:

                      • BANK_TRANSFER. Payments can be received through bank transfers.
                      • CASH. Payments can be received as cash.
                      • CHECK. Payments can be received as check.
                      • CREDIT_CARD. Payments can be received through credit card payments.
                      • DEBIT_CARD. Payments can be received through debit card payments.
                      • PAYPAL. Payments can be received through paypal payments.
                      • WIRE_TRANSFER. Payments can be received through wire transfer.
                      • OTHER. Payments can be received through other modes.
                    • note

                      string

                      A note associated with an external cash or check payment.

                      Maximum length: 2000.

                    • amount

                      object

                      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

                      object

                      The recipient's shipping information. Includes the user's contact information, which includes name and address.

                    payment_method

                    • payment_method

                      enum

                      The payment mode or method through which the invoicer can accept the payments.

                      The possible values are:

                      • BANK_TRANSFER. Payments can be received through bank transfers.
                      • CASH. Payments can be received as cash.
                      • CHECK. Payments can be received as check.
                      • CREDIT_CARD. Payments can be received through credit card payments.
                      • DEBIT_CARD. Payments can be received through debit card payments.
                      • PAYPAL. Payments can be received through paypal payments.
                      • WIRE_TRANSFER. Payments can be received through wire transfer.
                      • OTHER. Payments can be received through other modes.

                    payment_reference

                    • payment_id

                      string

                      The ID for the invoice payment.

                      Read only.

                    payment_term

                    • term_type

                      enum

                      The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.

                      The possible values are:

                      • DUE_ON_RECEIPT. The payment for the invoice is due upon receipt of the invoice.
                      • DUE_ON_DATE_SPECIFIED. The payment for the invoice is due on the date specified in the invoice.
                      • NET_10. The payment for the invoice is due in 10 days.
                      • NET_15. The payment for the invoice is due in 15 days.
                      • NET_30. The payment for the invoice is due in 30 days.
                      • NET_45. The payment for the invoice is due in 45 days.
                      • NET_60. The payment for the invoice is due in 60 days.
                      • NET_90. The payment for the invoice is due in 90 days.
                      • NO_DUE_DATE. The invoice has no payment due date.

                    payment_term_type

                    • payment_term_type

                      enum

                      The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.

                      The possible values are:

                      • DUE_ON_RECEIPT. The payment for the invoice is due upon receipt of the invoice.
                      • DUE_ON_DATE_SPECIFIED. The payment for the invoice is due on the date specified in the invoice.
                      • NET_10. The payment for the invoice is due in 10 days.
                      • NET_15. The payment for the invoice is due in 15 days.
                      • NET_30. The payment for the invoice is due in 30 days.
                      • NET_45. The payment for the invoice is due in 45 days.
                      • NET_60. The payment for the invoice is due in 60 days.
                      • NET_90. The payment for the invoice is due in 90 days.
                      • NO_DUE_DATE. The invoice has no payment due date.

                    payment_type

                    • payment_type

                      enum

                      The payment type. Can be PayPal or an external payment. Includes cash or a check.

                      The possible values are:

                      • PAYPAL. The payment type is PayPal.
                      • EXTERNAL. The payment type is an external cash or a check payment.

                    payments

                    • paid_amount

                      object

                      The aggregated payment amounts against this invoice.

                      Read only.

                    • transactions

                      array (contains the payment_detail object)

                      An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type.

                      Read only.

                    percentage

                    • percentage

                      string

                      The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.

                      Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

                    phone

                    • country_code

                      string

                      required

                      The country calling code (CC), in its canonical international E.164 numbering plan format. 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).

                      Minimum length: 1.

                      Maximum length: 3.

                      Pattern: ^[0-9]{1,3}?$.

                    • national_number

                      string

                      required

                      The national number, in its canonical international E.164 numbering plan format. 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).

                      Minimum length: 1.

                      Maximum length: 14.

                      Pattern: ^[0-9]{1,14}?$.

                    • extension_number

                      string

                      The extension number.

                      Minimum length: 1.

                      Maximum length: 15.

                      Pattern: ^[0-9]{1,15}?$.

                    phone_detail

                    • country_code

                      string

                      required

                      The country calling code (CC), in its canonical international E.164 numbering plan format. 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).

                      Minimum length: 1.

                      Maximum length: 3.

                      Pattern: ^[0-9]{1,3}?$.

                    • national_number

                      string

                      required

                      The national number, in its canonical international E.164 numbering plan format. 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).

                      Minimum length: 1.

                      Maximum length: 14.

                      Pattern: ^[0-9]{1,14}?$.

                    • extension_number

                      string

                      The extension number.

                      Minimum length: 1.

                      Maximum length: 15.

                      Pattern: ^[0-9]{1,15}?$.

                    • phone_type

                      string

                      The phone type.

                    phone_type

                    • phone_type

                      enum

                      The phone type.

                      Possible values: FAX,HOME,MOBILE,OTHER,PAGER.

                    qr_config

                    • width

                      integer

                      The width, in pixels, of the QR code image. Value is from 150 to 500.

                      Minimum value: 150.

                      Maximum value: 500.

                    • height

                      integer

                      The height, in pixels, of the QR code image. Value is from 150 to 500.

                      Minimum value: 150.

                      Maximum value: 500.

                    • action

                      string

                      The type of URL for which to generate a QR code. Valid values are pay and details.

                      Maximum length: 7.

                      Pattern: (?i)^(pay|details)$.

                    recipient_info

                    • billing_info

                      object

                      The billing information for the invoice recipient. Includes name, address, email, phone, and language.

                    • shipping_info

                      object

                      The recipient's shipping information. Includes the user's contact information, which includes name and address.

                    refund_detail

                    • type

                      enum

                      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.

                      The possible values are:

                      • PAYPAL. The payment type is PayPal.
                      • EXTERNAL. The payment type is an external cash or a check payment.

                      Read only.

                    • refund_id

                      string

                      The ID for a PayPal payment transaction. Required for the PAYPAL payment type.

                      Read only.

                      Maximum length: 22.

                    • refund_date

                      string

                      The date when the invoice was refunded, in Internet date format. For example, 2014-02-27.

                    • amount

                      object

                      The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.

                    • method

                      enum

                      required

                      The payment mode or method through which the invoicer can accept the payments.

                      The possible values are:

                      • BANK_TRANSFER. Payments can be received through bank transfers.
                      • CASH. Payments can be received as cash.
                      • CHECK. Payments can be received as check.
                      • CREDIT_CARD. Payments can be received through credit card payments.
                      • DEBIT_CARD. Payments can be received through debit card payments.
                      • PAYPAL. Payments can be received through paypal payments.
                      • WIRE_TRANSFER. Payments can be received through wire transfer.
                      • OTHER. Payments can be received through other modes.

                    refund_reference

                    • refund_id

                      string

                      The ID of the refund of an invoice payment.

                      Read only.

                    refunds

                    • refund_amount

                      object

                      The aggregated refund amounts.

                      Read only.

                    • transactions

                      array (contains the refund_detail object)

                      An array of refund details for the invoice. Includes the refund type, date, amount, and method.

                      Read only.

                    search_data

                    • recipient_email

                      string

                      Filters the search by the email address.

                      Maximum length: 254.

                    • recipient_first_name

                      string

                      Filters the search by the recipient first name.

                      Maximum length: 140.

                    • recipient_last_name

                      string

                      Filters the search by the recipient last name.

                      Maximum length: 140.

                    • recipient_business_name

                      string

                      Filters the search by the recipient business name.

                      Maximum length: 300.

                    • invoice_number

                      string

                      Filters the search by the invoice number.

                      Maximum length: 25.

                    • status

                      array (contains the invoice_status object)

                      An array of status values.

                    • reference

                      string

                      The reference data, such as a PO number.

                      Maximum length: 120.

                    • currency_code

                      string

                      The three-character ISO-4217 currency code that identifies the currency.

                    • memo

                      string

                      A private bookkeeping memo for the user.

                      Maximum length: 500.

                    • total_amount_range

                      object

                      Filters the search by the total amount.

                    • invoice_date_range

                      object

                      Filters the search by a date range for the invoice, in Internet date and time format.

                    • due_date_range

                      object

                      Filters the search by a due date range for the invoice, in Internet date and time format.

                    • payment_date_range

                      object

                      The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

                    • creation_date_range

                      object

                      Filters the search by a creation date range for the invoice, in Internet date and time format.

                    • archived

                      boolean

                      Indicates whether to list merchant-archived invoices in the response. Value is:

                      • true. Response lists only merchant-archived invoices.
                      • false. Response lists only unarchived invoices.
                      • null. Response lists all invoices.

                    • fields

                      array (contains the field object)

                      A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are items, payments, refunds, additional_recipients_info, and attachments.

                    shipping_cost

                    • amount

                      object

                      The shipping amount. Value is from 0 to 1000000. Supports up to two decimal places.

                    • tax

                      object

                      The tax associated with the shipping.

                    tax

                    • name

                      string

                      required

                      The name of the tax applied on the invoice items.

                      Maximum length: 100.

                    • percent

                      string

                      required

                      The tax rate. Value is from 0 to 100. Supports up to five decimal places.

                      Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

                    • amount

                      object

                      The calculated tax amount. The tax amount is added to the item total.

                      Read only.

                    template

                    • id

                      string

                      The ID of the template.

                      Read only.

                      Maximum length: 30.

                    • name

                      string

                      The template name.

                      Note: The template name must be unique.

                      Minimum length: 1.

                      Maximum length: 500.

                    • default_template

                      boolean

                      Indicates whether this template is the default template. A invoicer can have one default template.

                    • template_info

                      object

                      The template details. Includes invoicer business information, invoice recipients, items, and configuration.

                    • settings

                      object

                      The template settings. Describes which fields to show or hide when you create an invoice.

                    • unit_of_measure

                      enum

                      The unit of measure for the template. Value is quantity, hours, or amount.

                      The possible values are:

                      • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                      • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                      • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.
                    • standard_template

                      boolean

                      Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates.

                      Read only.

                    • links

                      array (contains the link_description object)

                      An array of request-related HATEOAS links.

                      Read only.

                    template_configuration

                    • tax_calculated_after_discount

                      boolean

                      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.

                    • tax_inclusive

                      boolean

                      Indicates whether the unit price includes tax.

                    • allow_tip

                      boolean

                      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.

                    • partial_payment

                      object

                      The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay.

                    template_detail

                    • reference

                      string

                      The reference data. Includes a post office (PO) number.

                      Maximum length: 120.

                    • currency_code

                      string

                      required

                      The three-character ISO-4217 currency code that identifies the currency.

                      Minimum length: 3.

                      Maximum length: 3.

                    • note

                      string

                      A note to the invoice recipient. Also appears on the invoice notification email.

                      Maximum length: 4000.

                    • terms_and_conditions

                      string

                      The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

                      Maximum length: 4000.

                    • memo

                      string

                      A private bookkeeping memo for the user.

                      Maximum length: 500.

                    • attachments

                      array (contains the file_reference object)

                      An array of PayPal IDs for the files that are attached to an invoice.

                    • payment_term

                      object

                      The payment due date for the invoice. Value is either but not both term_type or due_date.

                    • metadata

                      object

                      The audit metadata. Captures all template actions on create and update.

                    template_display_preference

                    • hidden

                      boolean

                      Indicates whether to show or hide this field.

                    template_info

                    • detail

                      object

                      The template-related details. Includes notes, terms and conditions, memo, and attachments.

                    • invoicer

                      object

                      The invoicer information. Includes business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

                    • primary_recipients

                      array (contains the recipient_info object)

                      The billing and shipping information. Includes name, email, address, phone, and language.

                    • additional_recipients

                      array (contains the email_address object)

                      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

                      array (contains the item object)

                      An array of invoice line-item information.

                    • configuration

                      object

                      The template configuration details. Includes tax information, tip, and partial payment.

                    • amount

                      object

                      The invoice amount summary of the item total, discount, tax total, and shipping.

                    • due_amount

                      object

                      The amount due for the invoice.

                      Read only.

                    template_item_field

                    • template_item_field

                      enum

                      The field names for the invoice line items in the template.

                      The possible values are:

                      • ITEMS_QUANTITY. The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.
                      • ITEMS_DESCRIPTION. The description of the item in the invoice template.
                      • ITEMS_DATE. The date in invoice template when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
                      • ITEMS_DISCOUNT. The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total.
                      • ITEMS_TAX. The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.

                    template_item_setting

                    • field_name

                      enum

                      The field name in template_data for which to map corresponding display preferences.

                      The possible values are:

                      • ITEMS_QUANTITY. The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.
                      • ITEMS_DESCRIPTION. The description of the item in the invoice template.
                      • ITEMS_DATE. The date in invoice template when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
                      • ITEMS_DISCOUNT. The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total.
                      • ITEMS_TAX. The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
                    • display_preference

                      object

                      The display preference.

                    template_metadata

                    • create_time

                      string

                      The date and time when the resource was created, in Internet date and time format.

                      Read only.

                    • created_by

                      string

                      The email address of the account that created the resource.

                      Read only.

                    • last_update_time

                      string

                      The date and time when the resource was last edited, in Internet date and time format.

                      Read only.

                    • last_updated_by

                      string

                      The email address of the account that last edited the resource.

                      Read only.

                    template_settings

                    • template_item_settings

                      array (contains the template_item_setting object)

                      The template item headers display preference.

                    • template_subtotal_settings

                      array (contains the template_subtotal_setting object)

                      The template subtotal headers display preference.

                    template_subtotal_field

                    • template_subtotal_field

                      enum

                      The field names in the template for discount, shipping, and custom amounts.

                      The possible values are:

                      • DISCOUNT. The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
                      • SHIPPING. The shipping fee for all items in the invoice template. Also includes the tax on shipping.
                      • CUSTOM. The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount.

                    template_subtotal_setting

                    • field_name

                      enum

                      The field name in template_data for which to map corresponding display preferences.

                      The possible values are:

                      • DISCOUNT. The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
                      • SHIPPING. The shipping fee for all items in the invoice template. Also includes the tax on shipping.
                      • CUSTOM. The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount.
                    • display_preference

                      object

                      The display preference.

                    templates

                    • addresses

                      array (contains the address_portable object)

                      An array of addresses in the user's PayPal profile.

                      Read only.

                    • emails

                      string

                      An array of emails in the user's PayPal profile.

                      Read only.

                    • phones

                      array (contains the phone_detail object)

                      An array of phone numbers in the user's PayPal profile.

                    • templates

                      array (contains the template object)

                      An array of details for each template. If fields is none, returns only the template name, ID, and default status.

                    • links

                      array (contains the link_description object)

                      An array of request-related HATEOAS links.

                      Read only.

                    unit_of_measure

                    • unit_of_measure

                      enum

                      The unit of measure for the invoiced item.

                      The possible values are:

                      • QUANTITY. The unit of measure is quantity. This invoice template is typically used for physical goods.
                      • HOURS. The unit of measure is hours. This invoice template is typically used for services.
                      • AMOUNT. The unit of measure is amount. This invoice template is typically used when only amount is required.

                    Additional API information

                    Error messages

                    In addition to common HTTP status codes that the REST APIs return, the Invoices API can return the following errors.

                    • INTERNAL_SERVER_ERROR

                      An internal server error occurred.

                    • INVALID_REQUEST

                      Request is not well-formed, syntactically incorrect, or violates schema. Possible issues are

                      • VALUE_CANNOT_BE_ZERO.

                        Payment amount cannot be zero. Please provide a valid amount.

                      • INVALID_STRING_MAX_LENGTH.

                        Field value exceeded the maximum allowed number of characters.

                      • MISSING_REQUIRED_PARAMETER.

                        Payment method is missing. Please pass a valid payment method.

                      • INVALID_PAYMENT_METHOD.

                        The value provided is not an acceptable method of payment.

                      • NOT_SUPPORTED.

                        Currency code is not supported.

                      • INVALID_STRING_LENGTH.

                        Currency code length should be 3 characters.

                      • MISSING_REQUIRED_PARAMETER.

                        Amount value is missing. Please provide a valid amount.

                      • INVALID_PARAMETER_SYNTAX.

                        Amount value is invalid. Should be a numeric value.

                      • INVALID_ARRAY_MAX_ITEMS.

                        Only maximum of 100 email address is supported in additional recipients.

                      • INVALID_DECIMAL_VALUE.

                        Payment amount value is invalid. Can have non-negative value with maximum 7 digits and upto 2 fractions.

                      • INVALID_INTEGER_VALUE.

                        Payment amount value is invalid. Can have non-negative value with maximum 6 digits.

                      • INVALID_PARAMETER_SYNTAX.

                        Date should be of format yyyy-mm-dd.

                      • INVALID_REFUND_METHOD.

                        The value provided is not an acceptable method of refund.

                      • INVALID_INTEGER_MAX_VALUE.

                        Value exceeds max value.

                      • INVALID_INTEGER_MIN_VALUE.

                        Value less than minimum value.

                      • TEMPLATE_NAME_ALREADY_EXISTS.

                        Template name already exists.

                    • NOT_AUTHORIZED

                      Authorization failed due to insufficient permissions. Possible issues are

                      • PERMISSION_DENIED.

                        The requested invoice cannot be fetched due to insufficient permissions.

                      • CANNOT_DELETE_GLOBAL_TEMPLATE.

                        Global templates cannot be deleted.

                    • RESOURCE_NOT_FOUND

                      The specified resource does not exist.

                    • UNPROCESSABLE_ENTITY

                      The requested action could not be performed, semantically incorrect, or failed business validation. Possible issues are

                      • INVOICE_CANCELED_ALREADY.

                        Invoice is already cancelled.

                      • INVOICE_ALREADY_SENT.

                        The Invoice is already sent.

                      • INVOICE_ALREADY_SHARED.

                        Invoice has already been shared via link.

                      • MISSING_RECIPIENT_EMAIL.

                        Missing recipient email address. Recipient email address is required to send invoice via PayPal.

                      • INVALID_SCHEDULE_DATE.

                        Invoice can only be scheduled for a future date no later than 365 days from today's date.

                      • CANNOT_CANCEL_DRAFT_INVOICE.

                        Draft invoice cannot be canceled.

                      • CANNOT_CANCEL_PAID_INVOICE.

                        Cannot cancel a paid or partially paid invoice.

                      • CANNOT_CANCEL_REFUNDED_INVOICE.

                        Cannot cancel a refunded or partially refunded invoice.

                      • CANNOT_CANCEL_SCHEDULED_INVOICE.

                        Cannot cancel a scheduled invoice.

                      • CANNOT_SEND_INVOICE.

                        Only DRAFT and UNPAID invoices can be sent.

                      • PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE.

                        Payment amount is greater than the amount due.

                      • INVALID_INVOICE_TYPE.

                        The invoice type is not valid for paying an invoice.

                      • INVALID_INVOICE_STATE.

                        Current invoice state does not support payment processing.

                      • INVALID_REFUND_AMOUNT.

                        Recorded refunds cannot exceed recorded payments.

                      • CANNOT_PROCESS_REFUNDS.

                        Current invoice state does not support refunds.

                      • INVOICE_CANNOT_BE_DELETED.

                        Only invoices in draft, scheduled, or canceled status can be deleted.

                      • CANNOT_DELETE_EXTERNAL_PAYMENT.

                        The external payment cannot be deleted as the recorded refund cannot exceed the recored payment for an invoice.

                      • CANNOT_REMIND_DRAFT_INVOICE.

                        You cannot remind an invoice which is in DRAFT status. Only UNPAID, SENT and PARTIALLY_PAID invoices can be reminded.

                      • USER_NOT_FOUND.

                        User is not associated with paypal based on invoicer email.

                    Popular Search Queries
                    PayPal Help
                    FAQ's

                    FAQ's

                    Forum

                    Tech Support Community

                    PayPal Community