Invoicing API

Use the Invoicing API to create, send, and manage invoices. You can also use the Invoicing API or webhooks to track invoice payments.

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

Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card.

For more information, see Invoicing overview.

Invoices (resource group)

Use the /invoicing/invoices resource to create, update, and send invoices and invoice reminders. To manage invoices, you can also search for, list, and show invoice details, and delete draft invoices and cancel sent invoices. You can also mark invoices as fully or partially paid, or as refunded. Lastly, you can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone.

Create draft invoice

POST /v1/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.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows invoice details.
Note: The merchant that you specify in an invoice must have a PayPal account in good standing.
.

Request

Specify an invoice object.

  • number

    string

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

    Maximum length: 25.

  • merchant_info

    object

    required

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system 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": "dlarusso@mail.com",
  "first_name": "David",
  "last_name": "Larusso",
  "business_name": "Mitchell & Murray",
  "phone": {
    "country_code": "001",
    "national_number": "4085551234"
  },
  "address": {
    "line1": "1234 First Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "98765",
    "country_code": "US"
  }
  },
  "billing_info": [
  {
    "email": "stmeyers@mail.com",
    "first_name": "Stephanie",
    "last_name": "Meyers"
  }
  ],
  "shipping_info": {
  "first_name": "Stephanie",
  "last_name": "Meyers",
  "address": {
    "line1": "1234 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "98765",
    "country_code": "US"
  }
  },
  "items": [
  {
    "name": "Zoom System wireless headphones",
    "quantity": 2,
    "unit_price": {
    "currency": "USD",
    "value": "120"
    },
    "tax": {
    "name": "Tax",
    "percent": 8
    }
  },
  {
    "name": "Bluetooth speaker",
    "quantity": 1,
    "unit_price": {
    "currency": "USD",
    "value": "145"
    },
    "tax": {
    "name": "Tax",
    "percent": 8
    }
  }
  ],
  "discount": {
  "percent": 1
  },
  "shipping_cost": {
  "amount": {
    "currency": "USD",
    "value": "10"
  }
  },
  "note": "Thank you for your business.",
  "terms": "No refunds after 30 days."
}'

Response

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

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

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

    Maximum length: 25.

  • uri

    string

    The URI of the invoice.

    Read only.

  • status

    enum

    The invoice status. When you search for invoices, specify this value as an array. For example, "status": ["REFUNDED"].

    Read only.

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

  • merchant_info

    object

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • payments

    array (contains the payment_detail object)

    The payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    The invoicing refund details.

    Read only.

  • metadata

    object

    The audit information for the invoice.

    Read only.

  • paid_amount

    object

    The payment summary of the invoice. Includes the amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file that is attached to an invoice or template.

    Read only.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system template.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "INV2-RUVR-ADWQ-H89Y-ABCD",
  "number": "INV 01256",
  "status": "DRAFT",
  "merchant_info": {
    "email": "dlarusso@mail.com",
    "first_name": "David",
    "last_name": "Larusso",
    "business_name": "Mitchell & Murray",
    "phone": {
      "country_code": "001",
      "national_number": "4085551234"
    },
    "address": {
      "line1": "1234 First Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "stmeyers@mail.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }
  ],
  "shipping_info": {
    "first_name": "Stephanie",
    "last_name": "Meyers",
    "address": {
      "line1": "1234 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Zoom System wireless headphones",
      "quantity": 2,
      "unit_price": {
        "currency": "USD",
        "value": "120.00"
      },
      "tax": {
        "name": "Tax",
        "percent": 8,
        "amount": {
          "currency": "USD",
          "value": "19.20"
        }
      }
    },
    {
      "name": "Bluetooth speaker",
      "quantity": 1,
      "unit_price": {
        "currency": "USD",
        "value": "145.00"
      },
      "tax": {
        "name": "Tax",
        "percent": 8,
        "amount": {
          "currency": "USD",
          "value": "11.60"
        }
      }
    }
  ],
  "invoice_date": "2017-06-22 PDT",
  "discount": {
    "percent": 10,
    "amount": {
      "currency": "USD",
      "value": "38.50"
    }
  },
  "shipping_cost": {
    "amount": {
      "currency": "USD",
      "value": "10.00"
    }
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Thank you for your business.",
  "total_amount": {
    "currency": "USD",
    "value": "387.30"
  },
  "metadata": {
    "created_date": "2017-06-22 09:39:04 PDT"
  },
  "allow_tip": false,
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
      "method": "GET"
    },
    {
      "rel": "send",
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX/send",
      "method": "POST"
    },
    {
      "rel": "update",
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX/update",
      "method": "PUT"
    },
    {
      "rel": "delete",
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
      "method": "DELETE"
    }
  ]
}

Send invoice

POST /v1/invoicing/invoices/invoice_id/send
Sends an invoice, by ID, to a customer. To suppress the merchant's email notification, set the notify_merchant query parameter to false.
A successful request returns the HTTP 202 Accepted status code with no JSON response body.
Note: After you send an invoice, you cannot resend it.

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: 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?notify_merchant=true \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Sample Response

202 Accepted

Update invoice

PUT /v1/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.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

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: true.

Request

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

  • number

    string

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

    Maximum length: 25.

  • merchant_info

    object

    required

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system 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",
  "address": {
    "line1": "1234 Broad St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97216",
    "country_code": "US"
  }
  }
}'

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.

  • number

    string

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

    Maximum length: 25.

  • uri

    string

    The URI of the invoice.

    Read only.

  • status

    enum

    The invoice status. When you search for invoices, specify this value as an array. For example, "status": ["REFUNDED"].

    Read only.

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

  • merchant_info

    object

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • payments

    array (contains the payment_detail object)

    The payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    The invoicing refund details.

    Read only.

  • metadata

    object

    The audit information for the invoice.

    Read only.

  • paid_amount

    object

    The payment summary of the invoice. Includes the amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file that is attached to an invoice or template.

    Read only.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system 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",
    "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 reminder

POST /v1/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.
A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Parameters

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

  • invoice_id

    path string

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

Request

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

  • subject

    string

    The subject of the notification. Default is a generic subject.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

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

    Default: true.

  • cc_emails

    array

    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 cc_info value associated with the invoice.
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 request returns the HTTP 202 Accepted status code with no JSON response body.

Sample Response

202 Accepted

Delete draft invoice

DELETE /v1/invoicing/invoices/invoice_id
Deletes draft invoices. You can cancel invoices that you have already sent.
After you delete a draft invoice, you can no longer use it or show its details. However, you can reuse its invoice number.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

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

  • invoice_id

    path string

    The ID of the draft 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 request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

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.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

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. If left blank we include a generic subject.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

    Indicates whether to send the notification to the merchant.

    Default: True.

  • send_to_payer

    boolean

    Indicates whether to send the notification to the payer.

    Default: True.

  • 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": "Invoice canceled",
  "note": "Canceling this invoice per your request.",
  "send_to_merchant": true,
  "send_to_payer": true,
  "cc_emails": [
  "cc-email@paypal.com"
  ]
}'

Response

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

Sample Response

204 No Content

Mark invoice as paid

POST /v1/invoicing/invoices/invoice_id/record-payment
Marks the status of an invoice, by ID, as paid.
A successful request returns the HTTP 200 OK status code with no JSON response body.

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, in Internet date and time format. For example, yyyy-MM-dd z.
  • method

    enum

    required

    The payment mode or method.

    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, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
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 request returns the HTTP 200 OK status code with no JSON response body.

Sample Response

200 OK

Mark invoice as refunded

POST /v1/invoicing/invoices/invoice_id/record-refund
Marks the status of an invoice, by ID, as refunded.
A successful request returns the HTTP 200 OK status code with no JSON response body.

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, in Internet date and time format. For example, 2014-02-27 PST.
  • 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 request returns the HTTP 200 OK status code with no JSON response body.

Sample Response

200 OK

List merchant invoices

GET /v1/invoicing/invoices
Lists merchant invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.

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

    The zero-relative start index of the entire list of merchant invoices that are returned in the response. So, the combination of page=0 and page_size=20 returns the first 20 invoices.The combination of page=20 and page_size=20 returns the next 20 invoices.

    Default: 1.

  • page_size

    query_string integer

    The number of invoices to return in the response.

    Default: 20.

  • total_count_required

    query_string boolean

    Indicates whether the to show the total count in the response.
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 request returns the HTTP 200 OK status code and a JSON response body that lists invoices with invoice details.

  • 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)

    The 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": {
        "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": {
        "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": {
        "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": {
        "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.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

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 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.

  • number

    string

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

    Maximum length: 25.

  • uri

    string

    The URI of the invoice.

    Read only.

  • status

    enum

    The invoice status. When you search for invoices, specify this value as an array. For example, "status": ["REFUNDED"].

    Read only.

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

  • merchant_info

    object

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • payments

    array (contains the payment_detail object)

    The payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    The invoicing refund details.

    Read only.

  • metadata

    object

    The audit information for the invoice.

    Read only.

  • paid_amount

    object

    The payment summary of the invoice. Includes the amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file that is attached to an invoice or template.

    Read only.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system 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",
    "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"
    }
  ]
}

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 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:
  1. Create an invoice.
  2. 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.

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

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. Value is from 150 to 500.

    Default: 500.

  • height

    query_string integer

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

    Default: 500.

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 request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a PNG image in base-64-encoded format.

  • image

    string

Sample Response

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

Generate invoice number

POST /v1/invoicing/invoices/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.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.

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

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

  • number

    string

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

Sample Response

{
  "number": "ee0044"
}

Templates (resource group)

You can use the /invoicing/templates resource to create, list, show details for, update, and delete invoice templates.

The template API is useful when creating a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template in order to populate the invoice data.

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

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.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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": {
  "merchant_info": {
    "email": "dennis_doctor@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"
    }
  },
  "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

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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. The system generates non-custom templates.

    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": {
    "merchant_info": {
      "email": "dennis_doctor@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"
      }
    },
    "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, specify a complete template object. The update method does not support partial updates.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details.

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.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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": {
  "merchant_info": {
    "email": "dennis_doctor@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"
    }
  },
  "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.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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. The system generates non-custom templates.

    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": {
    "merchant_info": {
      "email": "dennis_doctor@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"
      }
    },
    "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 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.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices.

Parameters

  • fields

    query_string 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.

    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)

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

    array

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

    array (contains the phone object)

    The phone number.
  • templates

    array (contains the template object)

    The 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",
      "country_code": "US"
    }
  ],
  "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": {
        "merchant_info": {
          "email": "dennis_doctor@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"
          }
        },
        "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.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details.

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.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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. The system generates non-custom templates.

    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": {
    "merchant_info": {
      "email": "dennis_doctor@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"
      }
    },
    "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.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

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

204 No Content

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-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).
  • 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-letter code for a US state or the equivalent for other countries.
  • phone

    string

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

amount_summary

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • paid_amount

    object

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

    Read only.

  • refunded_amount

    object

    The 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. If you omit this value, the invoice is payable and a notification email is not sent.

    Maximum length: 260.

  • phone

    object

    The invoice recipient's phone number.
  • first_name

    string

    The invoice recipient's first name.

    Maximum length: 30.

  • last_name

    string

    The invoice recipient's last name.

    Maximum length: 30.

  • business_name

    string

    The invoice recipient's business name.

    Maximum length: 100.

  • address

    object

    The invoice recipient's billing address.
  • language

    enum

    The language in which the invoice recipient's email appears. Used only when the recipient does not have a PayPal account.
    If you omit the language and the recipient does not have a PayPal account, the email is sent in the language of the merchant's PayPal account.

    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

    Any additional information about the recipient.

    Maximum length: 40.

cancel_notification

  • subject

    string

    The subject of the notification. If left blank we include a generic subject.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

    Indicates whether to send the notification to the merchant.

    Default: True.

  • send_to_payer

    boolean

    Indicates whether to send the notification to the payer.

    Default: True.

  • 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 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.

currency

  • currency

    string

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

    string

    The currency value. Might be an integer for currencies like JPY that are not typically fractional or a decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see ISO 4217.

custom_amount

  • label

    string

    The custom amount label.

    Maximum length: 50.

  • amount

    object

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

email

  • email

    string

    The participant's email address.

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)

    The details for an error. Required for client-side 4xx errors.

    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. Use this URL to download the file.

file_upload_response

  • message

    string

    The Document Management System (DMS) information.

    Maximum length: 200.

  • id

    string

    The encrypted DMS-returned path for invoices.
  • filename

    string

    The file name of the uploaded document.

group_invoicing_response

  • group_id

    string

    The ID for the group of invoices.

invoice

  • id

    string

    The ID of the invoice.

    Read only.

  • number

    string

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

    Maximum length: 25.

  • uri

    string

    The URI of the invoice.

    Read only.

  • status

    enum

    The invoice status. When you search for invoices, specify this value as an array. For example, "status": ["REFUNDED"].

    Read only.

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

  • merchant_info

    object

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the participant object)

    The participant information.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • invoice_date

    string

    The invoice date as specificed by the sender, in Internet date and time format. For example, yyyy-MM-dd z.
  • payment_term

    object

    The payment due date of the invoice. If you include due_date, the term_type value is ignored.
  • reference

    string

    The reference data, such as PO number.

    Maximum length: 60.

  • discount

    object

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

    object

    The shipping amount, 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.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. The note also appears on the invoice notification email.

    Maximum length: 4000.

  • merchant_memo

    string

    A private bookkeeping memo for the merchant.

    Maximum length: 500.

  • logo_url

    string

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

    Maximum length: 4000.

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • payments

    array (contains the payment_detail object)

    The payment details.

    Read only.

  • refunds

    array (contains the refund_detail object)

    The invoicing refund details.

    Read only.

  • metadata

    object

    The audit information for the invoice.

    Read only.

  • paid_amount

    object

    The payment summary of the invoice. Includes the amount paid through PayPal and other sources.

    Read only.

  • refunded_amount

    object

    The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file that is attached to an invoice or template.

    Read only.

  • 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 merchants in Hong Kong, Taiwan, India, or Japan.
  • template_id

    string

    The template ID. This value is used to determine the layout of the invoice, such as which fields to show and hide.

    Default: PayPal system 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. Value is from -10000 to 10000. Supports up to five decimal places.
  • unit_price

    object

    The item unit price. Value is from -1000000 to 1000000. Supports up to two decimal places.
  • tax

    object

    The tax associated with the item.
  • date

    string

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

    object

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

    enum

    The unit of measure for the invoiced item. For AMOUNT the unit_price and quantity are not shown on the invoice.
    Note: If your specify different unit_of_measure values for the same invoice, the invoice uses the first value.

    Possible values: QUANTITY, HOURS, AMOUNT.

invoice_number

  • number

    string

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

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)

    The invoice details.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

merchant_information

  • email

    string

    The merchant email address. This email must be listed in the merchant's PayPal profile.
    If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice.

    Maximum length: 260.

  • business_name

    string

    The merchant's business name.

    Maximum length: 100.

  • first_name

    string

    The merchant's first name.

    Maximum length: 256.

  • last_name

    string

    The merchant's last name.

    Maximum length: 256.

  • address

    object

    The merchant's address.
  • phone

    object

    The merchant's phone number.
  • fax

    object

    The merchant's fax number.
  • website

    string

    The merchant's website.

    Maximum length: 2048.

  • tax_id

    string

    The merchant's tax ID.

    Maximum length: 100.

  • additional_info

    string

    Any additional information, such as business hours.

    Maximum length: 40.

metadata

  • created_date

    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.

  • cancelled_date

    string

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

    Read only.

  • 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, 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.

  • first_sent_date

    string

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

    Read only.

  • last_sent_date

    string

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

    Read only.

  • last_sent_by

    string

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

    Read only.

  • payer_view_url

    string

    The URL for the payer's view of the invoice.

    Read only.

notification

  • subject

    string

    The subject of the notification. Default is a generic subject.
  • note

    string

    A note to the payer.
  • send_to_merchant

    boolean

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

    Default: true.

  • cc_emails

    array

    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 cc_info value associated with the invoice.

participant

  • email

    string

    The email address of the person who receives a copy of the invoice.

    Maximum length: 260.

payment_detail

  • type

    enum

    The payment type 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 for the PAYPAL payment type.

    Read only.

  • transaction_type

    enum

    The transaction type.

    Read only.

    Possible values: SALE, AUTHORIZATION, CAPTURE.

  • date

    string

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

    enum

    The payment mode or method.

    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, the total invoice amount is marked as paid. This amount cannot exceed the amount due.

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

    The term when 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, in Internet date and time format. For example, yyyy-MM-dd z.

phone

  • country_code

    string

    The country code portion of the phone number, in E.164 format.

    Minimum length: 1.

    Maximum length: 3.

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

  • national_number

    string

    The in-country phone number, in E.164 format.

    Minimum length: 1.

    Maximum length: 14.

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

qr_code

  • image

    string

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.

    Read only.

    Possible values: PAYPAL, EXTERNAL.

  • transaction_id

    string

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

    Read only.

  • date

    string

    The date when the invoice was refunded, in Internet date and time format. For example, 2014-02-27 PST.
  • 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 amount. Value is from 0 to 1000000. Supports up to two decimal places.
  • tax

    object

    The tax percentage on the shipping amount.

shipping_information

  • first_name

    string

    The first name of the recipient at the shipping address.

    Maximum length: 256.

  • last_name

    string

    The last name of the recipient at the shipping address.

    Maximum length: 256.

  • business_name

    string

    The business name of the recipient at the shipping address.

    Maximum length: 480.

  • address

    object

    The shipping address.

summaries

  • summaries

    array (contains the summary object)

    The summary of invoice data.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

summary

  • status

    enum

    The invoice status.

    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)

    The summary of the invoice total and paid and refunded amounts, grouped by currency code.

tax

  • name

    string

    The tax name.

    Maximum length: 100.

  • percent

    number

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

    object

    The calculated tax amount.

    Read only.

template

  • template_id

    string

    The ID of the template.

    Read only.

  • name

    string

    The template name.
    Note: The template name must be unique.
  • default

    boolean

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

    object

    The invoice data saved to 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. The system generates non-custom templates.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

template_data

  • merchant_info

    object

    The merchant information, such as business name, email, address, and so on.
  • billing_info

    array (contains the billing_info object)

    The billing information for the invoice recipient.
  • shipping_info

    object

    The shipping information for the recipient of the invoice.
  • cc_info

    array (contains the email object)

    The participant's email address.
  • items

    array (contains the invoice_item object)

    The invoice line item information.
  • payment_term

    object

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

    string

    The reference data, such as a PO number.

    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, the invoice must be paid in full. If true, the invoice allows partial payments.
    Note: This feature is not available for merchants in India, Brazil, or Israel.
  • minimum_amount_due

    object

    The minimum amount allowed for a partial payment. Valid only when 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.
  • tax_inclusive

    boolean

    Indicates whether the unit price includes tax.
  • terms

    string

    The general terms of the invoice.

    Maximum length: 4000.

  • note

    string

    A note to the invoice recipient. This note also appears on the invoice notification email.

    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. The logo image must not be larger than 250 pixels wide by 90 pixels high.

    Maximum length: 4000.

  • total_amount

    object

    The total amount of the invoice.

    Read only.

  • attachments

    array (contains the file_attachment object)

    The file that is attached to an invoice or template.

template_settings

  • field_name

    enum

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

    Possible values: items.quantity, items.description, items.date, items.discount, items.tax, discount, shipping, custom.

  • display_preference

    object

    The settings metadata for each field.

template_settings_metadata

  • hidden

    boolean

    Indicates whether to show or hide this field.

templates

  • addresses

    array (contains the address object)

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

    array

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

    array (contains the phone object)

    The phone number.
  • templates

    array (contains the template object)

    The 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 HTTP status codes that the REST APIs return, the Invoicing API can return the following errors.

  • 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.