Invoicing API

Use the Invoicing API to create draft invoices, send invoices, and manage invoices. You use invoices to track payments.

When you send an invoice, the invoice moves from draft to payable state and PayPal emails a link to the invoice on the PayPal website to the customer.

Customers with a PayPal account can log in and pay with PayPal. Alternatively, customers can pay with a check, debit card, or credit card.

For more information, see Invoicing overview.

Invoices (resource group)

Use the /invoicing/invoices resource to create, update, and send invoices and invoice reminders. You can also generate invoice QR codes and invoice numbers, search for, list, and show invoice details, and delete draft invoices and cancel sent invoices. You can mark invoices as fully or partially paid, or as refunded and delete an external payment or refund from an invoice.

Create invoice

POST /v1/invoicing/invoices
Creates a draft invoice. You can optionally create an invoice template. Then, when you create an invoice from a template, the invoice is populated with the predefined data that the source template contains. 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 specified in an invoice must have a PayPal account in good standing.

Request

Specify an invoice object.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • merchant_info

    object

    required

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "merchant_info": {
  "email": "ppaas_default@paypal.com",
  "first_name": "Dennis",
  "last_name": "Doctor",
  "business_name": "Medical Professionals, LLC",
  "phone": {
    "country_code": "001",
    "national_number": "5032141716"
  },
  "address": {
    "line1": "1234 Main St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97217",
    "country_code": "US"
  }
  },
  "billing_info": [{
  "email": "example@example.com"
  }],
  "items": [{
  "name": "Sutures",
  "quantity": 100,
  "unit_price": {
    "currency": "USD",
    "value": "5"
  }
  }],
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "payment_term": {
  "term_type": "NET_45"
  },
  "shipping_info": {
  "first_name": "Sally",
  "last_name": "Patient",
  "business_name": "Not applicable",
  "phone": {
    "country_code": "001",
    "national_number": "5039871234"
  },
  "address": {
    "line1": "1234 Broad St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97216",
    "country_code": "US"
  }
  }
}'

Response

A successful call returns an invoice object that includes the ID of the created invoice.

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • uri

    string

    The URI of the invoice.

    Read only.

    Format: uri.

  • status

    enum

    An enumeration of the invoice statuses.

    Read only.

    Possible values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING.

  • merchant_info

    object

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • payments

    array (contains the payment_detail object)

    Payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    Invoicing refund details.

    Read only.

  • metadata

    object

    Audit information for the invoice.

    Read only.

  • paid_amount

    object

    Payment summary of the invoice including amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    Payment summary of the invoice, including amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "INV2-RUVR-ADWQ-H89Y-ABCD",
  "number": "ABCD4971",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141234"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "email@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-02-27 PST",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-04-13 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Generate QR code

GET /v1/invoicing/invoices/invoice_id/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 a customer uses their mobile device to scan the QR code, he or she is redirected to the PayPal mobile payment flow where he or she can pay online with PayPal or a credit card.

Before you get a QR code, you must:
  1. Create an invoice. Specify qrinvoice@paypal.com as the recipient email address in the billing_info object. Use a customer email address only if you want to email the invoice.
  2. Send an invoice to move the invoice from a draft to payable state. If you specify qrinvoice@paypal.com as the recipient email address, the invoice is not emailed.

Parameters

In the request URI, specify the ID of the invoice that you want to get and append optional parameters, as needed.

  • invoice_id

    path string

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

    query_string integer

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

    Default: 500.

  • height

    query_string integer

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

    Default: 500.

  • action

    query_string string

    The type of URL for which to generate a QR code. Default is pay and is the only supported value.

    Default: pay.

SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-S6FG-ZZCK-VXMM-8KKP/qr-code \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns a QR code as a PNG image in base-64 encoded format and the HTTP 200 (OK) status code.

  • image

    string

Sample Response

{
  "image": "iVBORw0KGgoAA......XUDM"
}

List merchant invoices

GET /v1/invoicing/invoices

Lists invoices that belong to the merchant who makes the call.

Parameters

By default, the response shows the first 20 invoices that belong to the calling merchant.

To filter the response, use one or more of the following query parameters.

  • page

    query_string integer

    A zero-relative index of the list of merchant invoices.

    Default: 1.

  • page_size

    query_string integer

    The number of invoices to list beginning with the specified page.

    Default: 20.

  • total_count_required

    query_string boolean

    Indicates whether the total count appears in the response. Default is false.

    Default: false.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns an array that contains an invoice object for each invoice.

  • total_count

    see description

    The total number of invoices that match the search criteria.
    Possible types: integer

    Read only.

  • invoices

    array (contains the invoice object)

    Invoice details.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "total_count": 589,
  "invoices": [
    {
      "id": "INV2-2NB5-UJ7A-YSUJ-ABCD",
      "number": "9879878979003791",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 23:55:58 PST"
      }
    },
    {
      "id": "INV2-5AYC-UE5K-XXEG-ABCD",
      "number": "9879878979003790",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 19:41:56 PST"
      }
    },
    {
      "id": "INV2-C4QH-KEKM-C5QE-ABCD",
      "number": "9879878979003789",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 15:34:11 PST"
      }
    },
    {
      "id": "INV2-YP6Y-9LJU-9NFS-ABCD",
      "number": "9879878979003788",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "12.00"
      },
      "metadata": {
        "created_date": "2014-02-27 15:34:01 PST"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices?page=4&page_size=4&total_count_required=true",
      "rel": "next",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices?page=2&page_size=4&total_count_required=true",
      "rel": "previous",
      "method": "GET"
    }
  ]
}

Show invoice details

GET /v1/invoicing/invoices/invoice_id

Shows details for an invoice, by ID.

Parameters

In the request URI, provide the ID of the invoice for which to show details.

  • invoice_id

    path string

    The ID of the invoice for which to show details.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns an invoice object that shows invoice details.

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • uri

    string

    The URI of the invoice.

    Read only.

    Format: uri.

  • status

    enum

    An enumeration of the invoice statuses.

    Read only.

    Possible values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING.

  • merchant_info

    object

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • payments

    array (contains the payment_detail object)

    Payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    Invoicing refund details.

    Read only.

  • metadata

    object

    Audit information for the invoice.

    Read only.

  • paid_amount

    object

    Payment summary of the invoice including amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    Payment summary of the invoice, including amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "INV2-RF6D-L66T-D7H2-CRU7",
  "number": "0002",
  "status": "DRAFT",
  "template_id": "TEMP-XYZ",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  },
  "metadata": {
    "created_date": "2014-03-24 12:11:52 PDT"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/send",
      "rel": "send",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
      "rel": "update",
      "method": "PUT"
    }
  ]
}

Update invoice

PUT /v1/invoicing/invoices/invoice_id

Updates an invoice, by ID.

Parameters

In the request URI, pass the ID of the invoice to update.

  • invoice_id

    path string

    The ID of the invoice to update.
  • notify_merchant

    query_string boolean

    Indicates whether to send the invoice update notification to the merchant. Default is true.

    Default: true.

Request

In the JSON request body, provide an invoice object that contains the changes to make.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • merchant_info

    object

    required

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
SDK samples: C#, JAVA, Node.js, PHP

Sample Request

curl -v -X PUT https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-8UZ6-Q3DK-VZXV-SXQB \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "merchant_info": {
  "email": "ppaas_default@paypal.com",
  "first_name": "Dennis",
  "last_name": "Doctor",
  "business_name": "Medical Professionals, LLC",
  "phone": {
    "country_code": "001",
    "national_number": "5032141716"
  },
  "address": {
    "line1": "1234 Main St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97217",
    "country_code": "US"
  }
  },
  "billing_info": [
  {
    "email": "example@example.com"
  }
  ],
  "items": [
  {
    "name": "Sutures",
    "quantity": 100,
    "unit_price": {
    "currency": "USD",
    "value": "5"
    }
  }
  ],
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "payment_term": {
  "term_type": "NET_45"
  },
  "shipping_info": {
  "first_name": "Sally",
  "last_name": "Patient",
  "business_name": "Not applicable",
  "phone": {
    "country_code": "001",
    "national_number": "5039871234"
  },
  "address": {
    "line1": "1234 Broad St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97216",
    "country_code": "US"
  }
  }
}'

Response

Returns an invoice object that contains the specified changes.

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • uri

    string

    The URI of the invoice.

    Read only.

    Format: uri.

  • status

    enum

    An enumeration of the invoice statuses.

    Read only.

    Possible values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING.

  • merchant_info

    object

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • payments

    array (contains the payment_detail object)

    Payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    Invoicing refund details.

    Read only.

  • metadata

    object

    Audit information for the invoice.

    Read only.

  • paid_amount

    object

    Payment summary of the invoice including amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    Payment summary of the invoice, including amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "INV2-8UZ6-Q3DK-VZXV-SXQB",
  "number": "0014",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Generate invoice number

POST /v1/invoicing/invoices/next-invoice-number

Generates the next invoice number that is available to the user.

Sample Request

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

Response

  • number

    string

    The next invoice number that is available to the user. This number is auto-incremented from the most recent invoice number.

Sample Response

{
  "number": "ee0044"
}

Delete draft invoice

DELETE /v1/invoicing/invoices/invoice_id
Deletes a draft invoice, by ID. Note that this call works for invoices in the draft state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft invoice, you can no longer use it or show its details. However, you can reuse its invoice number.

Parameters

In the request URI, specify the ID of the invoice to delete.

  • invoice_id

    path string

    The ID of the invoice to delete.
SDK samples: C#, JAVA, Node.js, PHP

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-92MG-CNXV-ND7G-P3D2 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "id": "INV2-8UZ6-Q3DK-VZXV-SXQB",
  "number": "0014",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Send invoice

POST /v1/invoicing/invoices/invoice_id/send
Sends an invoice, by ID, to a customer.
Note: After you send an invoice, you cannot resend it.

Optionally, set the notify_merchant query parameter to also send the merchant an invoice update notification. Default is true.

Parameters

Specify the ID of the invoice to send.

  • invoice_id

    path string

    The ID of the invoice to send.
  • notify_merchant

    query_string boolean

    Indicates whether to send the invoice update notification to the merchant. Default is true.

    Default: true.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/send \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 202 (Accepted) status code.

Sample Response

202 Accepted

Send invoice reminder

POST /v1/invoicing/invoices/invoice_id/remind

Sends a reminder to the payer that a payment is due for an invoice, by ID.

Parameters

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

  • invoice_id

    path string

    The ID of the invoice.

Request

In the JSON request body, pass a notification object that contains reminder information.

  • subject

    string

    The subject of the notification.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

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

    array

    An array of one or more Cc: emails. If you omit this parameter from the JSON request body, a notification is sent to all Cc: email addresses that are part of the invoice. Otherwise, specify this parameter to limit the email addresses to which notifications are sent.
    Note: Additional email addresses are not supported.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/remind \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "subject": "Past due",
  "note": "Please pay soon",
  "send_to_merchant": true,
  "cc_emails": [
  "cc-email@paypal.com"
  ]
}'

Response

A successful call returns the HTTP 202 (Accepted) status code.

Sample Response

{
  "image": "iVBORw0KGgoAA......XUDM"
}

Cancel sent invoice

POST /v1/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.

Parameters

Specify the ID of the invoice to cancel.

  • invoice_id

    path string

    The ID of the invoice to cancel.

Request

In the JSON request body, pass a cancel_notification object that contains cancellation information.

  • subject

    string

    The subject of the notification.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

    Indicates whether to send the notification to the merchant.
  • send_to_payer

    boolean

    Indicates whether to send the notification to the payer.
  • cc_emails

    array

    An array of one or more Cc: emails. If you omit this parameter from the JSON request body, a notification is sent to all Cc: email addresses that are part of the invoice. Otherwise, specify this parameter to limit the email addresses to which a notification is sent.
    Note: Additional email addresses are not supported.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-WW57-VFCD-X5H4-XTUP/cancel \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "subject": "Past due",
  "note": "Canceling invoice",
  "send_to_merchant": true,
  "send_to_payer": true,
  "cc_emails": [
  "cc-email@paypal.com"
  ]
}'

Response

A successful call returns the HTTP 202 (Accepted) status code.

Sample Response

{
  "id": "INV2-8UZ6-Q3DK-VZXV-SXQB",
  "number": "0014",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Mark invoice as paid

POST /v1/invoicing/invoices/invoice_id/record-payment

Marks an invoice, by ID, as paid.

Parameters

Specify the ID of the invoice to mark as paid.

  • invoice_id

    path string

    The ID of the invoice to mark as paid.

Request

In the JSON request body, pass a payment-detail object that contains payment information.

  • date

    string

    The date when the invoice was paid. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date-time.

  • method

    enum

    required

    An enumeration of the payment modes or methods. Required with the EXTERNAL payment type.

    Allowed values: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER, OTHER.

  • note

    string

    Optional. A note associated with the payment.
  • amount

    object

    The payment amount to record against the invoice. If you omit this parameter, records the total invoice amount as paid.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/record-payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "method": "CASH",
  "date": "2013-11-06 03:30:00 PST",
  "note": "I got the payment by cash!",
  "amount": {
  "currency": "USD",
  "value": "20.00"
  }
}'

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "image": "iVBORw0KGgoAA......XUDM"
}

Mark invoice as refunded

POST /v1/invoicing/invoices/invoice_id/record-refund

Marks an invoice, by ID, as refunded.

Parameters

Specify the ID of the invoice to mark as refunded.

  • invoice_id

    path string

    The ID of the invoice to mark as refunded.

Request

In the JSON request body, pass a refund-detail object that contains refund information.

  • date

    string

    The date when the invoice was refunded. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format. For example, 2014-02-27 PST.

    Format: date-time.

  • note

    string

    A note associated with the refund.
  • amount

    object

    The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-T4UQ-VW4W-K7N7-XM2R/record-refund \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "date": "2013-11-10 14:00:00 PST",
  "note": "Refunded by cash!",
  "amount": {
  "currency": "USD",
  "value": "20.00"
  }
}'

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "image": "iVBORw0KGgoAA......XUDM"
}

Delete external payment

DELETE /v1/invoicing/invoices/invoice_id/payment-records/transaction_id

Deletes an external payment transaction, by ID, from an invoice, by ID.

Parameters

Specify the ID of the invoice from which to delete the transaction and the ID of the payment transaction to delete.

  • invoice_id

    path string

    The ID of the invoice from which to delete a payment transaction.
  • transaction_id

    path string

    The ID of the payment transaction to delete.

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-TBRZ-SWBK-7FQ9-AC8F/payment-records/EXTR-86F38350LX4353815 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "id": "INV2-8UZ6-Q3DK-VZXV-SXQB",
  "number": "0014",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Delete external refund

DELETE /v1/invoicing/invoices/invoice_id/refund-records/transaction_id

Deletes an external refund transaction, by ID, from an invoice, by ID.

Parameters

Specify the ID of the invoice from which to delete the transaction and the ID of the transaction to delete.

  • invoice_id

    path string

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

    path string

    The ID of the refund transaction to delete.

Sample Request

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

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "image": "iVBORw0KGgoAA......XUDM"
}

Templates (resource group)

You can create a template for an invoice, which enables you to create invoices with predefined data. You can use the /invoicing/templates resource to create, list, show details for, update, and delete templates.

Note: You can also use the Template Settings dashboard to create a template for an invoice.

Create template

POST /v1/invoicing/templates

Creates an invoice template. When you create an invoice from a template, the invoice is populated with the predefined data that the source template contains.

Note: You can use the Template Settings dashboard instead of the API to create an invoice template.

Request

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/templates/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
  "items": [
    {
    "name": "Nutri Bullet",
    "quantity": 1,
    "unit_price": {
      "currency": "USD",
      "value": "50.00"
    }
    }
  ],
  "merchant_info": {
    "email": "jaypatel512-facilitator@hotmail.com"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Thank you for your business.",
  "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
  {
    "field_name": "items.date",
    "display_preference": {
    "hidden": true
    }
  },
  {
    "field_name": "custom",
    "display_preference": {
    "hidden": true
    }
  }
  ]
}'

Response

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

    boolean

    Indicates whether this template is a merchant-created custom template. Non-custom templates are system generated.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [
      {
        "name": "Nutri Bullet",
        "quantity": 1,
        "unit_price": {
          "currency": "USD",
          "value": "50.00"
        }
      }
    ],
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
    {
      "field_name": "items.date",
      "display_preference": {
        "hidden": true
      }
    },
    {
      "field_name": "custom",
      "display_preference": {
        "hidden": true
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

List templates

GET /v1/invoicing/templates
Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.

Parameters

  • fields

    query_string string

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

    Default: all.

Sample Request

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

Response

A successful call returns an array that contains the user's email, address, and phone number and an array of template objects.

  • addresses

    array (contains the address object)

    Base address to use as billing address in a payment or to extend a shipping address.
  • emails

    array

    List of emails in merchant profile.
  • phones

    array (contains the phone object)

    The phone number.
  • templates

    array (contains the template object)

    Invoicing template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "addresses": [
    {
      "line1": "2211 N 1st Street",
      "city": "San Jose",
      "postal_code": "95131",
      "state": "CA"
    }
  ],
  "emails": [
    "invoicing-merchant@paypal.com",
    "invoicing-merch-store2@paypal.com"
  ],
  "phones": [
    {
      "country_code": "1",
      "national_number": "4085057783"
    },
    {
      "country_code": "1",
      "national_number": "4088064703"
    }
  ],
  "templates": [
    {
      "template_id": "TEMP-XYZ",
      "name": "Hours Template",
      "default": true,
      "unit_of_measure": "Hours",
      "template_data": {
        "items": [
          {
            "name": "Nutri Bullet",
            "quantity": 1,
            "unit_price": {
              "currency": "USD",
              "value": "50.00"
            }
          }
        ],
        "tax_calculated_after_discount": false,
        "tax_inclusive": false,
        "note": "Thank you for your business.",
        "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
      },
      "settings": [
        {
          "field_name": "items.date",
          "display_preference": {
            "hidden": true
          }
        },
        {
          "field_name": "custom",
          "display_preference": {
            "hidden": true
          }
        }
      ],
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates",
      "rel": "collection",
      "method": "GET"
    }
  ]
}

Show template details

GET /v1/invoicing/templates/template_id

Shows details for a template, by ID.

Parameters

In the request URI, provide the ID of the template for which to show details.

  • template_id

    path string

    The ID of the template for which to show details.

Sample Request

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

Response

A successful call returns a template object that contains details for the specified template.

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

    boolean

    Indicates whether this template is a merchant-created custom template. Non-custom templates are system generated.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [
      {
        "name": "Nutri Bullet",
        "quantity": 1,
        "unit_price": {
          "currency": "USD",
          "value": "50.00"
        }
      }
    ],
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
    {
      "field_name": "items.date",
      "display_preference": {
        "hidden": true
      }
    },
    {
      "field_name": "custom",
      "display_preference": {
        "hidden": true
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Update template

PUT /v1/invoicing/templates/template_id
Updates a template, by ID. In the JSON request body, pass a complete template object. The update method does not support partial updates.

Parameters

  • template_id

    path string

    The ID of the template to update.

Request

In the JSON request body, provide a template object that contains the changes to make.

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

Sample Request

curl -v -X PUT https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
  "items": [
    {
    "name": "Nutri Bullet",
    "quantity": 1,
    "unit_price": {
      "currency": "USD",
      "value": "50.00"
    }
    }
  ],
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Thank you for your business.",
  "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
  {
    "field_name": "items.date",
    "display_preference": {
    "hidden": true
    }
  },
  {
    "field_name": "custom",
    "display_preference": {
    "hidden": true
    }
  }
  ]
}'

Response

Returns a template object that contains the specified changes.

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

    boolean

    Indicates whether this template is a merchant-created custom template. Non-custom templates are system generated.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [
      {
        "name": "Nutri Bullet",
        "quantity": 1,
        "unit_price": {
          "currency": "USD",
          "value": "50.00"
        }
      }
    ],
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
    {
      "field_name": "items.date",
      "display_preference": {
        "hidden": true
      }
    },
    {
      "field_name": "custom",
      "display_preference": {
        "hidden": true
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Delete template

DELETE /v1/invoicing/templates/template_id

Deletes a template, by ID.

Parameters

In the request URI, specify the ID of the template to delete.

  • template_id

    path string

    The ID of the template to delete.

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-0JV3858360943364J \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 204 (No Content) status code.

Sample Response

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [
      {
        "name": "Nutri Bullet",
        "quantity": 1,
        "unit_price": {
          "currency": "USD",
          "value": "50.00"
        }
      }
    ],
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
    {
      "field_name": "items.date",
      "display_preference": {
        "hidden": true
      }
    },
    {
      "field_name": "custom",
      "display_preference": {
        "hidden": true
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Common object definitions

address

  • line1

    string

    The first line of the address. For example, number, street, and so on.
  • line2

    string

    Optional. The second line of the address. For example, suite, apt number, and so on.
  • city

    string

    The city name.
  • country_code

    string

    The two-letter code for a US state. Use the equivalent for other countries.
  • postal_code

    string

    The postal code, which is the zip code or equivalent. Typically required for countries with postal codes. For countries that have postal codes or an equivalent, see Postal code.
  • state

    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 is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE (for CUP, bank card, and cross-border transactions).
  • phone

    string

    A phone number. Must be represented in its canonical international format, as defined by the E.164 numbering plan.

    Format: phone.

amount_summary

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • paid_amount

    object

    Payment summary of invoice data including the amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    Payment summary of invoice data including the amount refunded through PayPal and other sources.

    Read only.

billing_info

  • email

    string

    The invoice recipient email address.
    Note:Before you get a QR code, you must create an invoice that specifies qrinvoice@paypal.comas the recipient email address in the billing_info object. Use a customer email address only if you want to email the invoice.

    Maximum length: 260.

    Format: email.

  • first_name

    string

    The invoice recipient first name.

    Maximum length: 30.

  • last_name

    string

    The invoice recipient last name.

    Maximum length: 30.

  • business_name

    string

    The invoice recipient company business name.

    Maximum length: 100.

  • address

    object

    The invoice recipient address.
  • language

    enum

    An enumeration of the languages in which an email can be sent to the recipient. Used only when the recipient lacks a PayPal account.

    Possible values: da_DK, de_DE, en_AU, en_GB, en_US, es_ES, es_XC, fr_CA, fr_FR, fr_XC, he_IL, id_ID, it_IT, ja_JP, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, zh_CN, zh_HK, zh_TW, zh_XC.

  • additional_info

    string

    Additional information, such as business hours.

    Maximum length: 40.

  • notification_channel

    enum

    An enumeration of the preferred notification channels for the recipient. Value is SMS or EMAIL. Default is EMAIL. For SMS, a phone value is required.

    Possible values: SMS, EMAIL.

  • phone

    object

    The mobile phone number to which to send SMS notification if notification_channel is SMS.

cancel_notification

  • subject

    string

    The subject of the notification.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

    Indicates whether to send the notification to the merchant.
  • send_to_payer

    boolean

    Indicates whether to send the notification to the payer.
  • cc_emails

    array

    An array of one or more Cc: emails. If you omit this parameter from the JSON request body, a notification is sent to all Cc: email addresses that are part of the invoice. Otherwise, specify this parameter to limit the email addresses to which a notification is sent.
    Note: Additional email addresses are not supported.

cost

  • percent

    number

    The cost, as a percent value. Valid value is from 0 to 100.
  • amount

    object

    The cost, as an amount value. Valid value is from 0 to 1,000,000.

currency

  • currency

    string

    The three-letter ISO 4217 alphabetic currency code.
  • value

    string

    The amount up to N digits after the decimal separator, as defined in ISO 4217 for the appropriate currency code.

custom_amount

  • label

    string

    The custom amount label.

    Maximum length: 50.

  • amount

    object

    The custom amount value. Valid value is from -999999.99 to 999999.99.

email

  • email

    string

    The participant email address.

    Format: email.

error

  • name

    string

    The human-readable and unique name of the error.

    Read only.

  • debug_id

    string

    The PayPal internal ID. Used for correlation purposes.

    Read only.

  • message

    string

    The message that describes the error.

    Read only.

  • information_link

    string

    The URI to use to get developer details for this error.

    Read only.

  • details

    array (contains the error_details object)

    Error details.

    Read only.

error_details

  • field

    string

    The name of the field that caused the error. Required for client-side errors.
  • issue

    string

    The reason that the error occurred.

file_attachment

  • name

    string

    The name of the attached file.
  • url

    string

    The URL of the attached file, which can be downloaded.

    Format: uri.

invoice

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

    The unique invoice number. If you omit this number, it is auto-incremented from the previous invoice number.

    Maximum length: 25.

  • template_id

    string

    The ID of the template from which to create the invoice. Useful for copy functionality.
  • uri

    string

    The URI of the invoice.

    Read only.

    Format: uri.

  • status

    enum

    An enumeration of the invoice statuses.

    Read only.

    Possible values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING.

  • merchant_info

    object

    Additional information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the participant object)

    Participant information.
  • shipping_info

    object

    The shipping information for entities to whom items are being shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • invoice_date

    string

    The date when the invoice was enabled. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • payment_term

    object

    Optional. The payment deadline for the invoice. Value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Required if allow_partial_payment is true.
  • 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. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL to an external logo image.

    Maximum length: 4000.

    Format: uri.

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • payments

    array (contains the payment_detail object)

    Payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    Invoicing refund details.

    Read only.

  • metadata

    object

    Audit information for the invoice.

    Read only.

  • paid_amount

    object

    Payment summary of the invoice including amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    Payment summary of the invoice, including amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

invoice_item

  • name

    string

    The item name.

    Maximum length: 200.

  • description

    string

    The item description.

    Maximum length: 1000.

  • quantity

    number

    The item quantity. Valid value is from -10000 to 10000.
  • unit_price

    object

    The item unit price. Valid value is from -1,000,000 to 1,000,000.
  • tax

    object

    The tax associated with the item.
  • date

    string

    The date when the item or service was provided. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

  • discount

    object

    The item discount, as a percent or an amount value.
  • unit_of_measure

    enum

    An enumeration of the units of measure for the invoiced item.

    Possible values: QUANTITY, HOURS, AMOUNT.

invoices

  • total_count

    see description

    The total number of invoices that match the search criteria.
    Possible types: integer

    Read only.

  • invoices

    array (contains the invoice object)

    Invoice details.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

merchant_information

  • email

    string

    The merchant email address.

    Maximum length: 260.

    Format: email.

  • first_name

    string

    The merchant first name.

    Maximum length: 30.

  • last_name

    string

    The merchant last name.

    Maximum length: 30.

  • address

    object

    The merchant address.
  • business_name

    string

    The merchant company business name.

    Maximum length: 100.

  • phone

    object

    The merchant phone number.
  • fax

    object

    The merchant fax number.
  • website

    string

    The merchant website.

    Maximum length: 2048.

    Format: uri.

  • tax_id

    string

    The merchant tax ID.

    Maximum length: 100.

  • additional_info_label

    string

    A label for the additional_info field.

    Maximum length: 40.

  • additional_info

    string

    Additional information, such as business hours.

    Maximum length: 40.

metadata

  • created_date

    string

    The date and time when the resource was created.

    Read only.

    Format: date-time.

  • created_by

    string

    The email address of the account that created the resource.

    Read only.

  • cancelled_date

    string

    The date and time when the resource was canceled.

    Read only.

    Format: date-time.

  • cancelled_by

    string

    The actor who canceled the resource.

    Read only.

  • last_updated_date

    string

    The date and time when the resource was last edited.

    Read only.

    Format: date-time.

  • last_updated_by

    string

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

    Read only.

  • first_sent_date

    string

    The date and time when the resource was first sent.

    Read only.

    Format: date-time.

  • last_sent_date

    string

    The date and time when the resource was last sent.

    Read only.

    Format: date-time.

  • last_sent_by

    string

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

    Read only.

  • payer_view_url

    string

    URL representing the payer's view of the invoice.

    Read only.

    Format: uri.

notification

  • subject

    string

    The subject of the notification.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

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

    array

    An array of one or more Cc: emails. If you omit this parameter from the JSON request body, a notification is sent to all Cc: email addresses that are part of the invoice. Otherwise, specify this parameter to limit the email addresses to which notifications are sent.
    Note: Additional email addresses are not supported.

participant

  • email

    string

    The participant email address.

    Format: email.

  • first_name

    string

    The participant first name.

    Maximum length: 256.

  • last_name

    string

    The participant last name.

    Maximum length: 256.

  • business_name

    string

    The participant company business name.

    Maximum length: 480.

  • phone

    object

    The participant phone number.
  • fax

    object

    The participant fax number.
  • website

    string

    The participant website.

    Maximum length: 4000.

    Format: uri.

  • additional_info

    string

    Additional information, such as business hours.

    Maximum length: 400.

  • address

    object

    The participant address.

payment_detail

  • type

    enum

    An enumeration of the payment types in an invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.

    Read only.

    Possible values: PAYPAL, EXTERNAL.

  • transaction_id

    string

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

    Read only.

  • transaction_type

    enum

    An enumeration of the transaction types.

    Read only.

    Possible values: SALE, AUTHORIZATION, CAPTURE.

  • date

    string

    The date when the invoice was paid. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date-time.

  • method

    enum

    An enumeration of the payment modes or methods. Required with the EXTERNAL payment type.

    Possible values: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER, OTHER.

  • note

    string

    Optional. A note associated with the payment.
  • amount

    object

    The payment amount to record against the invoice. If you omit this parameter, records the total invoice amount as paid.

payment_summary

  • paypal

    object

    The total amount paid or refunded through PayPal.

    Read only.

  • other

    object

    The total amount paid or refunded through other sources.

    Read only.

payment_term

  • term_type

    enum

    An enumeration of the terms by which the invoice payment is due.

    Possible values: DUE_ON_RECEIPT, DUE_ON_DATE_SPECIFIED, NET_10, NET_15, NET_30, NET_45, NET_60, NET_90, NO_DUE_DATE.

  • due_date

    string

    The date when the invoice payment is due. This date must be a future date. Date format is yyyy-MM-dd z, as defined in Internet Date/Time Format.

    Format: date.

phone

  • country_code

    string

    The country calling code (CC), as defined by E.164. The maximum combined length of CC+national is 15 digits.

    Minimum length: 1.

    Maximum length: 3.

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

  • national_number

    string

    The national number, as defined by E.164. A national number consists of national destination code (NDC) and subscriber number (SN). The maximum combined length of CC+national is 15 digits.

    Minimum length: 1.

    Maximum length: 14.

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

refund_detail

  • type

    enum

    An enumeration of the PayPal refund types. Indicates whether the refund was paid through PayPal or externally in invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.

    Read only.

    Possible values: PAYPAL, EXTERNAL.

  • transaction_id

    string

    The ID of the PayPal refund transaction. Required with the PAYPAL refund type.

    Read only.

  • date

    string

    The date when the invoice was refunded. The date format is yyyy-MM-dd z, as defined in Internet Date/Time Format. For example, 2014-02-27 PST.

    Format: date-time.

  • note

    string

    A note associated with the refund.
  • amount

    object

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

shipping_cost

  • amount

    object

    The shipping cost, as an amount value. Valid value is from 0 to 999999.99.
  • tax

    object

    The tax percentage on the shipping amount.

shipping_info

  • first_name

    string

    The invoice recipient first name.

    Maximum length: 30.

  • last_name

    string

    The invoice recipient last name.

    Maximum length: 30.

  • business_name

    string

    The invoice recipient company business name.

    Maximum length: 100.

  • address

    object

    The invoice recipient address.

summaries

  • summaries

    array (contains the summary object)

    Summary of invoice data.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

summary

  • status

    enum

    An enumeration of the invoice statuses.

    Read only.

    Possible values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID, PAYMENT_PENDING.

  • count

    see description

    The total count of invoices.
    Possible types: integer

    Read only.

  • amount_summary

    array (contains the amount_summary object)

    Summary of invoice total and paid and refunded amounts, grouped by currency code.

tax

  • id

    string

    The resource ID.

    Read only.

  • name

    string

    The tax name.

    Maximum length: 20.

  • percent

    number

    The tax rate. Valid value is from 0.001 to 99.999.
  • amount

    object

    The tax, as a monetary amount. Cannot be specified in a request.

    Read only.

template

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
  • default

    boolean

    Indicates whether this template is the default merchant template. A merchant can have one default template.
  • template_data

    object

    Customized invoice data, which is saved as the template.
  • settings

    array (contains the template_settings object)

    The template settings.
  • unit_of_measure

    string

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

    boolean

    Indicates whether this template is a merchant-created custom template. Non-custom templates are system generated.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

template_data

  • merchant_info

    object

    Information about the merchant who sends the invoice.
  • billing_info

    array (contains the billing_info object)

    Billing information for the invoice recipient.
  • cc_info

    array (contains the email object)

    The participant email address.

    Format: email.

  • shipping_info

    object

    The shipping information for entities to whom items are shipped.
  • items

    array (contains the invoice_item object)

    Invoice line item information.
  • payment_term

    object

    Optional. The payment deadline for the invoice. Valid value is either term_type or due_date but not both.
  • reference

    string

    Reference data, such as PO number, to add to the invoice.

    Maximum length: 60.

  • discount

    object

    The invoice level discount, as a percent or an amount value.
  • shipping_cost

    object

    The shipping cost, as a percent or an amount value.
  • custom

    object

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

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid if allow_partial_payment is true.
  • tax_calculated_after_discount

    boolean

    Indicates whether the invoice allows a partial payment. If false, invoice must be paid in full. If true, the invoice allows partial payments. Default is false.

    Default: false.

  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax. Default is false.

    Default: false.

  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the payer.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 150.

  • logo_url

    string

    The full URL of an external logo image.

    Maximum length: 4000.

    Format: uri.

  • total_amount

    object

    The base object for all financial value-related fields. For example, balance, payment due, and so on.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file attached to an invoice or template.

template_settings

  • field_name

    string

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

    object

    The settings metadata for each field.

template_settings_metadata

  • hidden

    boolean

    Indicates whether this field is hidden. Default is false.

templates

  • addresses

    array (contains the address object)

    Base address to use as billing address in a payment or to extend a shipping address.
  • emails

    array

    List of emails in merchant profile.
  • phones

    array (contains the phone object)

    The phone number.
  • templates

    array (contains the template object)

    Invoicing template.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Additional API information

Error messages

In addition to common REST API errors, the Invoicing API can return the following errors. Corrective action is provided where possible.

  • AUTHORIZATION_ERROR

    Authorization error occurred. Authorization error occurred. Please check your credentials.

  • BUSINESS_ERROR

    Invoicing business error. An invoicing business error occurred. Please refer the message for a brief description of the error.

  • INTERNAL_SERVICE_ERROR

    An internal service error has occurred. Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

  • MALFORMED_REQUEST_ERROR

    JSON request malformed. The JSON request is malformed. Please check the request and resend the request.

  • RESOURCE_NOT_FOUND_ERROR

    Resource not found. The resource requested is not found in the system.

  • UNKNOWN_ERROR

    Unknown exception occurred. An unknown error occurred. If this error continues, contact PayPal Merchant Technical Support.

  • USER_BUSINESS_ERROR

    User business error. User business error occurred. Please refer the message for a brief description of the error.

  • VALIDATION_ERROR

    Invalid request - see details. One or more validation errors have occurred. Please refer the details for specific validation errors.