Invoices (2)

API Version v2

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

Cancel sent invoice

post/v2/invoicing/invoices/{invoice_id}/cancel

Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to cancel.

Request Body schema:
required

The email or SMS notification that will be sent to the payer on cancellation.

subject
string <= 4000 characters

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

note
string <= 4000 characters

A note to the payer.

send_to_invoicer
boolean
Default: false

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

send_to_recipient
boolean
Default: true

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

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Responses
204

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

Request samples
{
  • "send_to_invoicer": true,
  • "send_to_recipient": true,
  • "additional_recipients": [
    • "user@example.com"
    ]
}
Response samples
application/json
{ }

Send invoice reminder

post/v2/invoicing/invoices/{invoice_id}/remind

Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a notification object that defines the subject of the reminder and other details.

Notes:
  • API caller can send only 2 reminders in a day.
.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

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

Request Body schema:

The email or SMS notification that will be sent to the payer for reminder.

subject
string <= 4000 characters

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

note
string <= 4000 characters

A note to the payer.

send_to_invoicer
boolean
Default: false

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

send_to_recipient
boolean
Default: true

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

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Responses
204

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

Request samples
{
  • "send_to_invoicer": true,
  • "additional_recipients": [
    • "customer-a@example.com",
    • "customer@example.com"
    ]
}
Response samples
application/json
{ }

Record payment for invoice

post/v2/invoicing/invoices/{invoice_id}/payments

Records a payment for the invoice. If no payment is due, the invoice is marked as PAID. Otherwise, the invoice is marked as PARTIALLY PAID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as paid.

Request Body schema:
required

The details of the payment to record against the invoice.

payment_id
string <= 22 characters

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

note
string <= 2000 characters

A note associated with an external cash or check payment.

payment_date
string <ppaas_date_notime_v2> (date_no_time) = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

method
required
string (payment_method)

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (contact_information)

The contact information of the user. Includes name and address.

Responses
200

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

Request samples
{
  • "method": "BANK_TRANSFER",
  • "payment_date": "2018-05-01",
  • "amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    }
}
Response samples
{
  • "payment_id": "EXTR-86F38350LX4353815"
}

Record refund for invoice

post/v2/invoicing/invoices/{invoice_id}/refunds

Records a refund for the invoice. If all payments are refunded, the invoice is marked as REFUNDED. Otherwise, the invoice is marked as PARTIALLY REFUNDED.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as refunded.

Request Body schema:
required

The details of the refund to record against the invoice.

refund_date
string <ppaas_date_notime_v2> (date_no_time) = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

method
required
string (payment_method)

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

Responses
200

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

Request samples
{
  • "method": "BANK_TRANSFER",
  • "refund_date": "2018-05-21",
  • "amount": {
    • "currency_code": "USD",
    • "value": "5.00"
    }
}
Response samples
{
  • "refund_id": "EXTR-2LG703375E477444T"
}

Show invoice details

get/v2/invoicing/invoices/{invoice_id}

Shows details for an invoice, by ID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice for which to show details.

Responses
200

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

Request samples 
Response samples 
application/json
{
  • "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "tax_note": "Reduced tax rate",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga T Shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}
Fully update invoice
put/v2/invoicing/invoices/{invoice_id}
Fully updates an invoice, by ID. In the JSON request body, include a complete invoice object. This call does not support partial updates. 
Notes:
  • API caller can change/modify recipient only 2 times in 72 hours.
.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice to update.


 
query Parameters
send_to_recipient
boolean
 Default:  true
Indicates whether to send the invoice update notification to the recipient.


 
send_to_invoicer
boolean
 Default:  true
Indicates whether to send the invoice update notification to the merchant.


 
Request Body schema: application/json
required
A representation of changes to make in the invoice.


Array of objects (recipient_info)   <= 100 items 
The billing and shipping information. Includes name, email, address, phone and language.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Array of objects (item)   <= 100 items 
An array of invoice line item information.


 
required
object (invoice_detail) 
The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.


 
object (invoicer_info) 
The invoicer business information that appears on the invoice.


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


 
object (amount_summary_detail) 
The invoice amount summary of item total, discount, tax total, and shipping.


 
object (payments) 
An array of payments registered against the invoice.


 
object (refunds) 
The invoicing refund details. Includes the refund type, date, amount, and method.


 
Responses 
200
A successful request returns the HTTP 200 OK status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.


Request samples 
application/json
{
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-refernce-update",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      }
    },
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "www.test.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "tax_note": "Reduced tax rate",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    }
}
Response samples 
{
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}
Delete invoice
delete/v2/invoicing/invoices/{invoice_id}
Deletes a draft or scheduled invoice, by ID. Deletes invoices in the draft or scheduled state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the draft invoice to delete.


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


Request samples 
Response samples 
application/json
{ }
Create draft invoice
post/v2/invoicing/invoices
Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.
Note: The merchant that you specify in an invoice must have a PayPal account in good standing.
.


SecurityOauth2 
Request 
Request Body schema: 
required
The invoice details which includes all information of the invoice like items, billing information.


Array of objects (recipient_info)   <= 100 items 
The billing and shipping information. Includes name, email, address, phone and language.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Array of objects (item)   <= 100 items 
An array of invoice line item information.


 
required
object (invoice_detail) 
The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.


 
object (invoicer_info) 
The invoicer business information that appears on the invoice.


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


 
object (amount_summary_detail) 
The invoice amount summary of item total, discount, tax total, and shipping.


 
object (payments) 
An array of payments registered against the invoice.


 
object (refunds) 
The invoicing refund details. Includes the refund type, date, amount, and method.


 
Responses 
200
OK


Request samples 
{
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      }
    },
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "www.test.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25"
        },
      • "discount": {
        • "percent": "5"
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "tax_note": "Reduced tax rate"
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "breakdown": {
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25"
          }
        },
      • "discount": {
        • "invoice_discount": {
          • "percent": "5"
          }
        }
      }
    }
}
Response samples 
application/json
{
  • "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27",
          • "tax_note": "Reduced tax rate"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga T Shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34",
          • "tax_note": "Reduced tax rate"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73",
            • "tax_note": "Reduced tax rate"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}
List invoices
get/v2/invoicing/invoices
Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.


SecurityOauth2 
Request 
query Parameters
page
integer  [ 1 .. 1000 ] 
 Default:  1
The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.


 
page_size
integer  [ 1 .. 100 ] 
 Default:  20
The maximum number of invoices to return in the response.


 
total_required
boolean
 Default:  false
Indicates whether the to show total_pages and total_items in the response.


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


 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.


Request samples 
{ }
Response samples 
{}
Delete external refund
delete/v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}
Deletes an external refund, by invoice ID and transaction ID.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice from which to delete the external refund transaction.


 
transaction_id
required
string
The ID of the external refund transaction to delete.


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


Request samples 
Response samples 
application/json
{ }
Send invoice
post/v2/invoicing/invoices/{invoice_id}/send
Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:
  • If the invoice issue date is current or in the past, sends the invoice immediately.
  • If the invoice issue date is in the future, schedules the invoice to be sent on that date.
To suppress the merchant's email notification, set the send_to_invoicer body parameter to false. To send the invoice through a share link and not through PayPal, set the send_to_recipient parameter to false in the notification object. The send_to_recipient parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.
Notes:
  • After you send an invoice, resending it has no effect.
  • To send a notification for updates, update the invoice and set the send_to_recipient body parameter to true.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice to send.


 
Request Body schema: 
The email or SMS notification to send to the payer when they send an invoice..


subject
string  <= 4000 characters 
The subject of the email that is sent as a notification to the recipient.


 
note
string  <= 4000 characters 
A note to the payer.


 
send_to_invoicer
boolean
 Default:  false
Indicates whether to send a copy of the email to the merchant.


 
send_to_recipient
boolean
 Default:  true
Indicates whether to send a copy of the email to the recipient.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Responses 
202
Accepted


Request samples 
{
  • "send_to_invoicer": true
}
Response samples 
application/json
{ }
Show template details
get/v2/invoicing/templates/{template_id}
Shows details for a template, by ID.


SecurityOauth2 
Request 
path Parameters
template_id
required
string  [ 1 .. 22 ] characters ^(@default|TEMP-[A-Z0-9]{17})$
The ID of the template for which to show details.


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


Request samples 
Response samples 
{
  • "id": "TEMP-19V05281TU309413B",
  • "name": "reference-temp",
  • "default_template": true,
  • "template_info": {
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": true,
      • "partial_payment": {
        • "allow_partial_payment": true,
        • "minimum_amount_due": {
          • "currency_code": "USD",
          • "value": "20.00"
          }
        }
      },
    • "detail": {},
    • "invoicer": {
      • "name": {
        • "given_name": "David",
        • "surname": "Larusso"
        },
      • "address": {
        • "address_line_1": "1234 First Street",
        • "address_line_2": "337673 Hillside Court",
        • "admin_area_2": "Anytown",
        • "admin_area_1": "CA",
        • "postal_code": "98765",
        • "country_code": "US"
        },
      • "email_address": "merchant@example.com",
      • "phones": [
        • {
          • "country_code": "001",
          • "national_number": "4085551234",
          • "phone_type": "MOBILE"
          }
        ],
      • "website": "www.test.com",
      • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      • "logo_url": "https://example.com/logo.PNG",
      • "additional_notes": "2-4"
      },
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "bill-me@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4884551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "additional_info": "add-info"
          },
        • "shipping_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            }
          }
        }
      ],
    • "additional_recipients": [
      • "inform-me@example.com"
      ],
    • "items": [
      • {
        • "id": "ITEM-9R873787D1610780X",
        • "name": "Yoga Mat",
        • "description": "new watch",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "50.00"
          },
        • "tax": {
          • "id": "TAX-9R873787D1610780X",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "tax_note": "Reduced tax rate",
          • "amount": {
            • "currency_code": "USD",
            • "value": "3.27"
            }
          },
        • "discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "2.5"
            }
          },
        • "unit_of_measure": "QUANTITY"
        },
      • {
        • "id": "ITEM-4XD34145EH4061035",
        • "name": "Yoga T Shirt",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "id": "TAX-4XD34145EH4061035",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.34"
            }
          },
        • "discount": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "5.00"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "amount": {
      • "currency_code": "USD",
      • "value": "74.21",
      • "breakdown": {
        • "item_total": {
          • "currency_code": "USD",
          • "value": "60.00"
          },
        • "custom": {
          • "label": "Packing Charges",
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            }
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            },
          • "tax": {
            • "name": "Sales Tax",
            • "percent": "7.25",
            • "amount": {
              • "currency_code": "USD",
              • "value": "0.73"
              }
            }
          },
        • "discount": {
          • "item_discount": {
            • "currency_code": "USD",
            • "value": "-7.50"
            },
          • "invoice_discount": {
            • "percent": "5",
            • "amount": {
              • "currency_code": "USD",
              • "value": "-2.63"
              }
            }
          },
        • "tax_total": {
          • "currency_code": "USD",
          • "value": "4.34"
          }
        }
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.tax",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.description",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.quantity",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "custom",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "shipping",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY",
  • "standard_template": false,
  • "links": []
}
Fully update template
put/v2/invoicing/templates/{template_id}
Fully updates a template, by ID. In the JSON request body, include a complete template object. This call does not support partial updates.


SecurityOauth2 
Request 
path Parameters
template_id
required
string
The ID of the template for which to show details.


 
Request Body schema: application/json
required
A representation of changes to make in the template.


name
string  [ 1 .. 500 ] characters 
The template name.
Note: The template name must be unique.


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


 
object (template_info) 
The template details. Includes invoicer business information, invoice recipients, items, and configuration.


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


 
unit_of_measure
string (unit_of_measure) 
The unit of measure for the invoiced item.


 Enum Value Description
QUANTITY
The unit of measure is quantity. This invoice template is typically used for physical goods.


HOURS
The unit of measure is hours. This invoice template is typically used for services.


AMOUNT
The unit of measure is amount. This invoice template is typically used when only amount is required.


 
Responses 
200
A successful request returns the HTTP 200 OK status code. A JSON response body that shows template details is returned if you set prefer=return=representation.


Request samples 
application/json
{
  • "default_template": true,
  • "template_info": {
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": true,
      • "partial_payment": {
        • "allow_partial_payment": true,
        • "minimum_amount_due": {
          • "currency_code": "USD",
          • "value": "20.00"
          }
        }
      },
    • "detail": {},
    • "invoicer": {
      • "name": {
        • "given_name": "David",
        • "surname": "Larusso"
        },
      • "address": {
        • "address_line_1": "1234 First Street",
        • "address_line_2": "337673 Hillside Court",
        • "admin_area_2": "Anytown",
        • "admin_area_1": "CA",
        • "postal_code": "98765",
        • "country_code": "US"
        },
      • "email_address": "merchant@example.com",
      • "phones": [
        • {
          • "country_code": "001",
          • "national_number": "4085551234",
          • "phone_type": "MOBILE"
          }
        ],
      • "website": "www.test.com",
      • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      • "logo_url": "https://example.com/logo.PNG",
      • "additional_notes": "2-4"
      },
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "bill-me@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4884551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "additional_info": "add-info"
          },
        • "shipping_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            }
          }
        }
      ],
    • "additional_recipients": [
      • "inform-me@example.com"
      ],
    • "items": [
      • {
        • "name": "Yoga Mat",
        • "description": "new watch",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "50.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "tax_note": "Reduced tax rate"
          },
        • "discount": {
          • "percent": "5"
          },
        • "unit_of_measure": "QUANTITY"
        },
      • {
        • "name": "Yoga T Shirt",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25"
          },
        • "discount": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "5.00"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "amount": {
      • "currency_code": "USD",
      • "value": "74.21",
      • "breakdown": {
        • "custom": {
          • "label": "Packing Charges",
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            }
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            },
          • "tax": {
            • "name": "Sales Tax",
            • "percent": "7.25"
            }
          },
        • "discount": {
          • "invoice_discount": {
            • "percent": "5"
            }
          }
        }
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.tax",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.description",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.quantity",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "custom",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "shipping",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY",
  • "standard_template": false
}
Response samples 
application/json
{
  • "id": "TEMP-19V05281TU309413B",
  • "name": "reference-temp",
  • "default_template": true,
  • "template_info": {
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": true,
      • "partial_payment": {
        • "allow_partial_payment": true,
        • "minimum_amount_due": {
          • "currency_code": "USD",
          • "value": "20.00"
          }
        }
      },
    • "detail": {},
    • "invoicer": {
      • "name": {
        • "given_name": "David",
        • "surname": "Larusso"
        },
      • "address": {
        • "address_line_1": "1234 First Street",
        • "address_line_2": "337673 Hillside Court",
        • "admin_area_2": "Anytown",
        • "admin_area_1": "CA",
        • "postal_code": "98765",
        • "country_code": "US"
        },
      • "email_address": "merchant@example.com",
      • "phones": [
        • {
          • "country_code": "001",
          • "national_number": "4085551234",
          • "phone_type": "MOBILE"
          }
        ],
      • "website": "www.test.com",
      • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      • "logo_url": "https://example.com/logo.PNG",
      • "additional_notes": "2-4"
      },
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "bill-me@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4884551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "additional_info": "add-info"
          },
        • "shipping_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            }
          }
        }
      ],
    • "additional_recipients": [
      • "inform-me@example.com"
      ],
    • "items": [
      • {
        • "id": "ITEM-9R873787D1610780X",
        • "name": "Yoga Mat",
        • "description": "new watch",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "50.00"
          },
        • "tax": {
          • "id": "TAX-9R873787D1610780X",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "3.27"
            }
          },
        • "discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "2.5"
            }
          },
        • "unit_of_measure": "QUANTITY"
        },
      • {
        • "id": "ITEM-4XD34145EH4061035",
        • "name": "Yoga T Shirt",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "id": "TAX-4XD34145EH4061035",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.34"
            }
          },
        • "discount": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "5.00"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "amount": {
      • "currency_code": "USD",
      • "value": "74.21",
      • "breakdown": {
        • "item_total": {
          • "currency_code": "USD",
          • "value": "60.00"
          },
        • "custom": {
          • "label": "Packing Charges",
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            }
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            },
          • "tax": {
            • "name": "Sales Tax",
            • "percent": "7.25",
            • "amount": {
              • "currency_code": "USD",
              • "value": "0.73"
              }
            }
          },
        • "discount": {
          • "item_discount": {
            • "currency_code": "USD",
            • "value": "-7.50"
            },
          • "invoice_discount": {
            • "percent": "5",
            • "amount": {
              • "currency_code": "USD",
              • "value": "-2.63"
              }
            }
          },
        • "tax_total": {
          • "currency_code": "USD",
          • "value": "4.34"
          }
        }
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.tax",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.description",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.quantity",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "custom",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "shipping",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY",
  • "standard_template": false,
  • "links": []
}
Delete template
delete/v2/invoicing/templates/{template_id}
Deletes a template, by ID.


SecurityOauth2 
Request 
path Parameters
template_id
required
string
The ID of the template to delete.


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


Request samples 
Response samples 
application/json
{ }
Delete external payment
delete/v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}
Deletes an external payment, by invoice ID and transaction ID.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice from which to delete an external payment transaction.


 
transaction_id
required
string
The ID of the external payment transaction to delete.


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


Request samples 
Response samples 
application/json
{ }
Search for invoices
post/v2/invoicing/search-invoices
Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.


SecurityOauth2 
Request 
query Parameters
page
integer  [ 1 .. 1000 ] 
 Default:  1
The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.


 
page_size
integer  [ 1 .. 100 ] 
 Default:  20
The page size for the search results.


 
total_required
boolean
 Default:  false
Indicates whether the to show total_pages and total_items in the response.


 
Request Body schema: 
The invoice search can be used to retrieve the invoices based on the search parameters.


recipient_email
string  <= 254 characters 
Filters the search by the email address.


 
recipient_first_name
string  <= 140 characters 
Filters the search by the recipient first name.


 
recipient_last_name
string  <= 140 characters 
Filters the search by the recipient last name.


 
recipient_business_name
string  <= 300 characters 
Filters the search by the recipient business name.


 
invoice_number
string  <= 25 characters 
Filters the search by the invoice number.


 
status
Array of strings (invoice_status)   <= 5 items 
An array of status values.


Items Enum Value Description
DRAFT
The invoice is in draft state. It is not yet sent to the payer.


SENT
The invoice has been sent to the payer. The payment is awaited from the payer.


SCHEDULED
The invoice is scheduled on a future date. It is not yet sent to the payer.


PAID
The payer has paid for the invoice.


MARKED_AS_PAID
The invoice is marked as paid by the invoicer.


CANCELLED
The invoice has been cancelled by the invoicer.


REFUNDED
The invoice has been refunded by the invoicer.


PARTIALLY_PAID
The payer has partially paid for the invoice.


PARTIALLY_REFUNDED
The invoice has been partially refunded by the invoicer.


MARKED_AS_REFUNDED
The invoice is marked as refunded by the invoicer.


UNPAID
The invoicer is yet to receive the payment from the payer for the invoice.


PAYMENT_PENDING
The invoicer is yet to receive the payment for the invoice. It is under pending review.


 
reference
string  <= 120 characters 
The reference data, such as a PO number.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
archived
boolean
Indicates whether to list merchant-archived invoices in the response. Value is:
  • true. Response lists only merchant-archived invoices.
  • false. Response lists only unarchived invoices.
  • null. Response lists all invoices.


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


 
currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
object (amount_range) 
The amount range.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


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


Request samples 
{
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "USD",
      • "value": "50.00"
      },
    • "upper_amount": {
      • "currency_code": "USD",
      • "value": "50.00"
      }
    },
  • "invoice_date_range": {
    • "start": "2018-06-01",
    • "end": "2018-06-21"
    }
}
Response samples 
{}
List templates
get/v2/invoicing/templates
Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template.


SecurityOauth2 
Request 
query Parameters
fields
string(?i)^(all|none)$
 Default:  "all"
The fields to return in the response. Value is all or none. To return only the template name, ID, and default attributes, specify none.


 
page
integer  [ 1 .. 1000 ] 
 Default:  1
The page number to be retrieved, for the list of templates. So, a combination of page=1 and page_size=20 returns the first 20 templates. A combination of page=2 and page_size=20 returns the next 20 templates.


 
page_size
integer  [ 1 .. 100 ] 
 Default:  20
The maximum number of templates to return in the response.


 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices.


Request samples 
{ }
Response samples 
{
  • "addresses": [
    • {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • {
      • "address_line_1": "26303 E 8216 N",
      • "address_line_2": "045608 Ocean Bay Plaza #02",
      • "admin_area_2": "Garden City",
      • "admin_area_1": "NY",
      • "postal_code": "11530",
      • "country_code": "US"
      }
    ],
  • "emails": "email@example.com, email2@example.com",
  • "phones": [
    • {
      • "country_code": "001",
      • "national_number": "4085551234",
      • "phone_type": "HOME"
      },
    • {
      • "country_code": "1",
      • "national_number": "3477832250",
      • "phone_type": "MOBILE"
      },
    • {
      • "country_code": "1",
      • "national_number": "3479543267",
      • "phone_type": "FAX"
      },
    • {
      • "country_code": "1",
      • "national_number": "7183514942",
      • "phone_type": "OTHER"
      }
    ],
  • "templates": [
    • {
      • "id": "TEMP-19V05281TU309413B",
      • "name": "reference-temp",
      • "default_template": true,
      • "template_info": {
        • "configuration": {
          • "tax_calculated_after_discount": true,
          • "tax_inclusive": false,
          • "allow_tip": true,
          • "partial_payment": {
            • "allow_partial_payment": true,
            • "minimum_amount_due": {
              • "currency_code": "USD",
              • "value": "20.00"
              }
            }
          },
        • "detail": {},
        • "invoicer": {
          • "name": {
            • "given_name": "David",
            • "surname": "Larusso"
            },
          • "address": {
            • "address_line_1": "1234 First Street",
            • "address_line_2": "337673 Hillside Court",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "merchant@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4085551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "website": "www.test.com",
          • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
          • "logo_url": "https://example.com/logo.PNG",
          • "additional_notes": "2-4"
          },
        • "primary_recipients": [
          • {
            • "billing_info": {
              • "name": {
                • "given_name": "Stephanie",
                • "surname": "Meyers"
                },
              • "address": {
                • "address_line_1": "1234 Main Street",
                • "admin_area_2": "Anytown",
                • "admin_area_1": "CA",
                • "postal_code": "98765",
                • "country_code": "US"
                },
              • "email_address": "bill-me@example.com",
              • "phones": [
                • {
                  • "country_code": "001",
                  • "national_number": "4884551234",
                  • "phone_type": "MOBILE"
                  }
                ],
              • "additional_info": "add-info"
              },
            • "shipping_info": {
              • "name": {
                • "given_name": "Stephanie",
                • "surname": "Meyers"
                },
              • "address": {
                • "address_line_1": "1234 Main Street",
                • "admin_area_2": "Anytown",
                • "admin_area_1": "CA",
                • "postal_code": "98765",
                • "country_code": "US"
                }
              }
            }
          ],
        • "additional_recipients": [
          • "inform-me@example.com"
          ],
        • "items": [
          • {
            • "id": "ITEM-9R873787D1610780X",
            • "name": "Yoga Mat",
            • "description": "new watch",
            • "quantity": "1",
            • "unit_amount": {
              • "currency_code": "USD",
              • "value": "50.00"
              },
            • "tax": {
              • "id": "TAX-9R873787D1610780X",
              • "name": "Sales Tax",
              • "percent": "7.25",
              • "amount": {
                • "currency_code": "USD",
                • "value": "3.27"
                }
              },
            • "discount": {
              • "percent": "5",
              • "amount": {
                • "currency_code": "USD",
                • "value": "2.5"
                }
              },
            • "unit_of_measure": "QUANTITY"
            },
          • {
            • "id": "ITEM-4XD34145EH4061035",
            • "name": "Yoga t-shirt",
            • "quantity": "1",
            • "unit_amount": {
              • "currency_code": "USD",
              • "value": "10.00"
              },
            • "tax": {
              • "id": "TAX-4XD34145EH4061035",
              • "name": "Sales Tax",
              • "percent": "7.25",
              • "amount": {
                • "currency_code": "USD",
                • "value": "0.34"
                }
              },
            • "discount": {
              • "amount": {
                • "currency_code": "USD",
                • "value": "5.00"
                }
              },
            • "unit_of_measure": "QUANTITY"
            }
          ],
        • "amount": {
          • "currency_code": "USD",
          • "value": "74.21",
          • "breakdown": {
            • "item_total": {
              • "currency_code": "USD",
              • "value": "60.00"
              },
            • "custom": {
              • "label": "Packing Charges",
              • "amount": {
                • "currency_code": "USD",
                • "value": "10.00"
                }
              },
            • "shipping": {
              • "amount": {
                • "currency_code": "USD",
                • "value": "10.00"
                },
              • "tax": {
                • "name": "Sales Tax",
                • "percent": "7.25",
                • "amount": {
                  • "currency_code": "USD",
                  • "value": "0.73"
                  }
                }
              },
            • "discount": {
              • "item_discount": {
                • "currency_code": "USD",
                • "value": "-7.50"
                },
              • "invoice_discount": {
                • "percent": "5",
                • "amount": {
                  • "currency_code": "USD",
                  • "value": "-2.63"
                  }
                }
              },
            • "tax_total": {
              • "currency_code": "USD",
              • "value": "4.34"
              }
            }
          }
        },
      • "settings": {
        • "template_item_settings": [
          • {
            • "field_name": "items.date",
            • "display_preference": {
              • "hidden": true
              }
            },
          • {
            • "field_name": "items.discount",
            • "display_preference": {
              • "hidden": false
              }
            },
          • {
            • "field_name": "items.tax",
            • "display_preference": {
              • "hidden": false
              }
            },
          • {
            • "field_name": "items.description",
            • "display_preference": {
              • "hidden": false
              }
            },
          • {
            • "field_name": "items.quantity",
            • "display_preference": {
              • "hidden": true
              }
            }
          ],
        • "template_subtotal_settings": [
          • {
            • "field_name": "custom",
            • "display_preference": {
              • "hidden": false
              }
            },
          • {
            • "field_name": "discount",
            • "display_preference": {
              • "hidden": false
              }
            },
          • {
            • "field_name": "shipping",
            • "display_preference": {
              • "hidden": false
              }
            }
          ]
        },
      • "unit_of_measure": "QUANTITY",
      • "standard_template": false,
      • "links": []
      },
    • {
      • "default_template": true,
      • "id": "TEMP-11E67842VH3080617",
      • "name": "Quantity",
      • "template_info": {
        • "invoicer": {
          • "name": {
            • "given_name": "David",
            • "surname": "Larusso"
            },
          • "email_address": "bill-me@example.com"
          },
        • "detail": {
          • "currency_code": "USD"
          }
        },
      • "standard_template": false,
      • "links": []
      },
    • {
      • "default_template": false,
      • "id": "TEMP-6HC14139B8663074X",
      • "name": "Hours",
      • "template_info": {
        • "invoicer": {
          • "name": {
            • "given_name": "David",
            • "surname": "Larusso"
            },
          • "email_address": "bill-me@example.com"
          },
        • "detail": {
          • "currency_code": "USD"
          }
        },
      • "standard_template": false,
      • "links": []
      }
    ]
}
Create template
post/v2/invoicing/templates
Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.
Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes Quantity, Hours, and Amount.


SecurityOauth2 
Request 
Request Body schema: 
required
name
string  [ 1 .. 500 ] characters 
The template name.
Note: The template name must be unique.


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


 
object (template_info) 
The template details. Includes invoicer business information, invoice recipients, items, and configuration.


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


 
unit_of_measure
string (unit_of_measure) 
The unit of measure for the invoiced item.


 Enum Value Description
QUANTITY
The unit of measure is quantity. This invoice template is typically used for physical goods.


HOURS
The unit of measure is hours. This invoice template is typically used for services.


AMOUNT
The unit of measure is amount. This invoice template is typically used when only amount is required.


 
Responses 
200
OK


Request samples 
{
  • "default_template": true,
  • "template_info": {
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": true,
      • "partial_payment": {
        • "allow_partial_payment": true,
        • "minimum_amount_due": {
          • "currency_code": "USD",
          • "value": "20.00"
          }
        }
      },
    • "detail": {},
    • "invoicer": {
      • "name": {
        • "given_name": "David",
        • "surname": "Larusso"
        },
      • "address": {
        • "address_line_1": "1234 First Street",
        • "address_line_2": "337673 Hillside Court",
        • "admin_area_2": "Anytown",
        • "admin_area_1": "CA",
        • "postal_code": "98765",
        • "country_code": "US"
        },
      • "email_address": "merchant@example.com",
      • "phones": [
        • {
          • "country_code": "001",
          • "national_number": "4085551234",
          • "phone_type": "MOBILE"
          }
        ],
      • "website": "www.test.com",
      • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      • "logo_url": "https://example.com/logo.PNG",
      • "additional_notes": "2-4"
      },
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "bill-me@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4884551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "additional_info": "add-info"
          },
        • "shipping_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            }
          }
        }
      ],
    • "additional_recipients": [
      • "inform-me@example.com"
      ],
    • "items": [
      • {
        • "name": "Yoga Mat",
        • "description": "new watch",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "50.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25"
          },
        • "discount": {
          • "percent": "5"
          },
        • "unit_of_measure": "QUANTITY"
        },
      • {
        • "name": "Yoga T Shirt",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "tax_note": "Reduced tax rate"
          },
        • "discount": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "5.00"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "amount": {
      • "currency_code": "USD",
      • "value": "74.21",
      • "breakdown": {
        • "custom": {
          • "label": "Packing Charges",
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            }
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            },
          • "tax": {
            • "name": "Sales Tax",
            • "percent": "7.25"
            }
          },
        • "discount": {
          • "invoice_discount": {
            • "percent": "5"
            }
          }
        }
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.tax",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.description",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.quantity",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "custom",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "shipping",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY",
  • "standard_template": false
}
Response samples 
application/json
{
  • "id": "TEMP-19V05281TU309413B",
  • "name": "reference-temp",
  • "default_template": true,
  • "template_info": {
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": true,
      • "partial_payment": {
        • "allow_partial_payment": true,
        • "minimum_amount_due": {
          • "currency_code": "USD",
          • "value": "20.00"
          }
        }
      },
    • "detail": {},
    • "invoicer": {
      • "name": {
        • "given_name": "David",
        • "surname": "Larusso"
        },
      • "address": {
        • "address_line_1": "1234 First Street",
        • "address_line_2": "337673 Hillside Court",
        • "admin_area_2": "Anytown",
        • "admin_area_1": "CA",
        • "postal_code": "98765",
        • "country_code": "US"
        },
      • "email_address": "merchant@example.com",
      • "phones": [
        • {
          • "country_code": "001",
          • "national_number": "4085551234",
          • "phone_type": "MOBILE"
          }
        ],
      • "website": "www.test.com",
      • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
      • "logo_url": "https://example.com/logo.PNG",
      • "additional_notes": "2-4"
      },
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            },
          • "email_address": "bill-me@example.com",
          • "phones": [
            • {
              • "country_code": "001",
              • "national_number": "4884551234",
              • "phone_type": "MOBILE"
              }
            ],
          • "additional_info": "add-info"
          },
        • "shipping_info": {
          • "name": {
            • "given_name": "Stephanie",
            • "surname": "Meyers"
            },
          • "address": {
            • "address_line_1": "1234 Main Street",
            • "admin_area_2": "Anytown",
            • "admin_area_1": "CA",
            • "postal_code": "98765",
            • "country_code": "US"
            }
          }
        }
      ],
    • "additional_recipients": [
      • "inform-me@example.com"
      ],
    • "items": [
      • {
        • "id": "ITEM-9R873787D1610780X",
        • "name": "Yoga Mat",
        • "description": "new watch",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "50.00"
          },
        • "tax": {
          • "id": "TAX-9R873787D1610780X",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "3.27"
            }
          },
        • "discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "2.5"
            }
          },
        • "unit_of_measure": "QUANTITY"
        },
      • {
        • "id": "ITEM-4XD34145EH4061035",
        • "name": "Yoga T Shirt",
        • "quantity": "1",
        • "unit_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "id": "TAX-4XD34145EH4061035",
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.34"
            }
          },
        • "discount": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "5.00"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "amount": {
      • "currency_code": "USD",
      • "value": "74.21",
      • "breakdown": {
        • "item_total": {
          • "currency_code": "USD",
          • "value": "60.00"
          },
        • "custom": {
          • "label": "Packing Charges",
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            }
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "USD",
            • "value": "10.00"
            },
          • "tax": {
            • "name": "Sales Tax",
            • "percent": "7.25",
            • "amount": {
              • "currency_code": "USD",
              • "value": "0.73"
              }
            }
          },
        • "discount": {
          • "item_discount": {
            • "currency_code": "USD",
            • "value": "-7.50"
            },
          • "invoice_discount": {
            • "percent": "5",
            • "amount": {
              • "currency_code": "USD",
              • "value": "-2.63"
              }
            }
          },
        • "tax_total": {
          • "currency_code": "USD",
          • "value": "4.34"
          }
        }
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.tax",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.description",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "items.quantity",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "custom",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "discount",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "shipping",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY",
  • "standard_template": false,
  • "links": []
}
Generate QR code
post/v2/invoicing/invoices/{invoice_id}/generate-qr-code
Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must create an invoice and send an invoice to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed.


SecurityOauth2 
Request 
path Parameters
invoice_id
required
string
The ID of the invoice for which to generate a QR code.


 
Request Body schema: 
Optional configuration parameters to adjust QR code width, height and the encoded URL.


width
integer  [ 150 .. 500 ] 
 Default:  500
The width, in pixels, of the QR code image. Value is from 150 to 500.


 
height
integer  [ 150 .. 500 ] 
 Default:  500
The height, in pixels, of the QR code image. Value is from 150 to 500.


 
action
string  <= 7 characters (?i)^(pay|details)$
 Default:  "pay"
The type of URL for which to generate a QR code. Valid values are pay and details.


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


Request samples 
{
  • "width": 400,
  • "height": 400
}
Response samples 
multipart/form-data
--95dbdbed-7536-4c24-b5ca-bcdbc0006612 Content-Disposition: form-data; name="image" Content-Type: application/octet-stream iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABxUlEQVR42u2WMY7kIBBFq0VA1n0BS1yDjCvZF7DxBdxXIuMaSFzAzgiQaz6t9mxLm1AbrCYYy4H1AlT1f9XHxH89lX7Z/2KJKN3CMIW6FCInYplLPtisoU6FTyHzti6RN5tPm+5ixrtTp0uP8g8s744eMS1yxvikNEOJz966GPTLaOL1fmjaxfAkaLCy2t2Hl10sPUIaNY1araFhCat3TbODDPkZ68Ii1sqfX62c1rzP62W8uWG0aiMaxSyvpS4hez2MzXkZg+FL4NNCwku/XtZ8g/Be550+Pe9jWj0x41rt1ngZyxzYa+NpmDjNMlYx1yhhs2glM8vY3IQ3qGWz9Tqvk7F3cGyYNd3KQDKGSWFGDjFNIZ8yhuWgR8gb5jR8+9bJ8rPUCd3oYbY4VcQqaWSYWRGcdnhnSS+D6lhKJIE5+JrTXtaquDtzuuypXrV0stRKwLAUzFodnYjxERP28ihtLw8WsbQE7JbxCD9SmxMxfsUYpiZ7lxYWMewltzuqKMz4n13tYi3vl6jW2FJQynBH+Za7Zie6sZRhNVXLTkqTmGUE5xSRu5dv3Qz3uYdj0bwkFLGWfxxoJMXx28tO9vu/9oPYF0bR/hBeOiwMAAAAAElFTkSuQmCC --95dbdbed-7536-4c24-b5ca-bcdbc0006612--
Generate invoice number
post/v2/invoicing/generate-next-invoice-number
Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after INVOICE-1234 is INVOICE-1235.


SecurityOauth2 
Request 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.


Request samples 
{ }
Response samples 
application/json
{
  • "invoice_number": "ee0044"
}
Definitions
aggregated_discount
The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.


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


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "invoice_discount": {
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "item_discount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
amount_range
The amount range.


required
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
required
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "lower_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "upper_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
amount_summary_detail
The invoice amount summary of item total, discount, tax total, and shipping.


currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
value
string  <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be:
  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.


 
object (amount_with_breakdown) 
The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any.


 
{
  • "currency_code": "str",
  • "value": "string",
  • "breakdown": {
    • "item_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "discount": {
      • "invoice_discount": {
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "item_discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "tax_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping": {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "tax_note": "string",
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      },
    • "custom": {
      • "label": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    }
}
amount_with_breakdown
The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any.


object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (aggregated_discount) 
The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (shipping_cost) 
The shipping fee for all items. Includes tax on shipping.


 
object (custom_amount) 
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


 
{
  • "item_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "discount": {
    • "invoice_discount": {
      • "percent": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "item_discount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "tax_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping": {
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "tax": {
      • "name": "string",
      • "tax_note": "string",
      • "percent": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "custom": {
    • "label": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}
batch_date_range
Filters between the start and end dates inclusive. 
  • Both dates cannot be more than 1 month in the past.
  • Both dates cannot be more than 3 months from current date.
  •  Start date should be before end date.


start_date
required
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The start date of the range. Cannot be more than 1 month the past. Cannot be more than 3 months in the future. Cannot be after the end date.


 
end_date
required
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The end date of the range. Cannot be more than 1 month the past. Cannot be more than 3 months in the future. Cannot be before the start date.


 
{
  • "start_date": "stringstri",
  • "end_date": "stringstri"
}
batch_task_summary
The details about the batch task.


id
string (id)   = 40 characters ^(BAT-)1[0-9A-Z]{3}-[0-9A-Z]{4}-[0-9A-Z]{8}-[...
A unique id used to reference the batch task.


 
task_type
string (task_type)   [ 1 .. 50 ] characters ^[A-Z0-9_]*$
Task type of the batch task. Used to determine the batch operation/logic to be performed.


 Enum Value Description
RISK_LIMIT_RECENT
Task for processing recent records for the account in Invoicing.


RISK_LIMIT_FULL
Task for processing all records in Invoicing.


 
task_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The task date as specified by the sender, in Internet date and time format. Date cannot be in the past.


 
{
  • "id": "stringstringstringstringstringstringstri",
  • "task_type": "RISK_LIMIT_RECENT",
  • "task_date": "stringstri"
}
billing_info
The billing information of the invoice recipient. Includes name, address, email, phone, and language.


business_name
string  <= 300 characters 
Required. The business name of the party.


 
object (Name) 
The name of the party.


 
object (Portable Postal Address (Medium-Grained)) 
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


 
Array of objects (phone_detail) 
The invoice recipient's phone numbers. Extension number is not supported.


 
additional_info
string  <= 40 characters 
Any additional information about the recipient.


 
email_address
string (restrictive_email_address)   [ 3 .. 254 ] characters ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(...
The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part. 
  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
language
string <ppaas_common_language_v3>  (language)   [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.


 
{
  • "business_name": "string",
  • "name": {
    • "prefix": "string",
    • "given_name": "string",
    • "surname": "string",
    • "middle_name": "string",
    • "suffix": "string",
    • "alternate_full_name": "string",
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      }
    },
  • "phones": [
    • {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string",
      • "phone_type": "FAX"
      }
    ],
  • "additional_info": "string",
  • "email_address": "string",
  • "language": "string"
}
Business Name
The business name of the party.


business_name
string  <= 300 characters 
Required. The business name of the party.


 
{
  • "business_name": "string"
}
configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.


tax_calculated_after_discount
boolean
 Default:  true
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
 Default:  false
Indicates whether the unit price includes tax.


 
allow_tip
boolean
 Default:  false
Indicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.
Note: This feature is not available for users in Hong Kong, Taiwan, India, or Japan.


 
object (partial_payment) 
The partial payment details. Includes the minimum amount that the invoicer expects from the payer.


 
template_id
string  <= 30 characters 
 Default:  "PayPal system template"
The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.


 
{
  • "tax_calculated_after_discount": true,
  • "tax_inclusive": false,
  • "allow_tip": false,
  • "partial_payment": {
    • "allow_partial_payment": false,
    • "minimum_amount_due": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "template_id": "PayPal system template"
}
contact_information
The contact information of the user. Includes name and address.


business_name
string  <= 300 characters 
Required. The business name of the party.


 
object (Name) 
The name of the party.


 
object (Portable Postal Address (Medium-Grained)) 
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


 
{
  • "business_name": "string",
  • "name": {
    • "prefix": "string",
    • "given_name": "string",
    • "surname": "string",
    • "middle_name": "string",
    • "suffix": "string",
    • "alternate_full_name": "string",
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      }
    }
}
country_code
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


 
"st"
country_code
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


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


string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
"str"
custom_amount
The custom amount to apply to an invoice. If you include a label, you must include a custom amount.


label
required
string  <= 50 characters 
The label to the custom amount of the invoice.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "label": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
Date and Time Range
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


start
required
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
end
required
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
{
  • "start": "string",
  • "end": "string"
}
date_no_time
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
"stringstri"
date_range
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


start
required
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
end
required
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
{
  • "start": "string",
  • "end": "string"
}
date_time
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
"stringstringstringst"
detail
The details of the invoice like notes, terms and conditions, memo, attachments.


reference
string  <= 120 characters 
The reference data. Includes a Purchase Order (PO) number.


 
note
string  <= 4000 characters 
A note to the invoice recipient. Also appears on the invoice notification email.


 
terms_and_conditions
string  <= 4000 characters 
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
Array of objects (File Reference)   <= 5 
An array of PayPal IDs for the files that are attached to an invoice.


 
currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
{
  • "reference": "string",
  • "note": "string",
  • "terms_and_conditions": "string",
  • "memo": "string",
  • "attachments": [
    • {
      • "id": "string",
      • "reference_url": "http://example.com",
      • "content_type": "string",
      • "size": "string",
      • "create_time": "string"
      }
    ],
  • "currency_code": "string"
}
discount
The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.


percent
string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "percent": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
email
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


string <merchant_common_email_address_v2>  (email)   [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
"string"
email_address
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


string <ppaas_common_email_address_v2>  (email_address)   [ 3 .. 254 ] characters ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za...
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
"string"
Error
The error details.


name
required
string
The human-readable, unique name of the error.


 
message
required
string
The message that describes the error.


 
debug_id
required
string
The PayPal internal ID. Used for correlation purposes.


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


 
Array of objects (Error Details) 
An array of additional details about the error.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ]
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Error Details
The error details. Required for client-side 4XX errors.


field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.


 
value
string
The value of the field that caused the error.


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


 
issue
required
string
The unique, fine-grained application-level error code.


 
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.


 
Array of objects (Link Description)   [ 1 .. 4 ] items 
An array of request-related HATEOAS links that are either relevant to the issue by providing additional information or offering potential resolutions.


 
{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Estimate
Estimate information, this contains the information about the estimate like item, amount, billing and shipping information.


id
string  [ 1 .. 30 ] characters ^[A-Z0-9_-]+$
The ID of the estimate.


 
status
string  [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Represents estimate status.


 Enum Value Description
DRAFT
Draft estimate.


SENT
Estimate sent.


CANCELLED
Estimate cancelled.


SHARED
Estimate shared.


ACCEPTED
Estimate accepted.


DELETED
Estimate deleted.


INVOICED
Estimate invoiced.


EXPIRED
Estimate expired.


 
required
object (estimate_detail) 
The details of the estimate. Includes estimate number, date and audit metadata.


 
object (invoicer_info) 
The invoicer business information that appears on the invoice.


 
Array of objects (recipient_info)   [ 1 .. 100 ] items 
The billing and shipping information. Includes name, email, address, phone and language.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   [ 1 .. 100 ] items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Array of objects (item)   [ 1 .. 100 ] items 
An array of estimate line item information.


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


 
object (amount_summary_detail) 
The invoice amount summary of item total, discount, tax total, and shipping.


 
Array of objects (Link Description)   [ 1 .. 7 ] items 
An array of request-related HATEOAS links.


 
{
  • "id": "string",
  • "status": "DRAFT",
  • "detail": {
    • "reference": "string",
    • "note": "string",
    • "terms_and_conditions": "string",
    • "memo": "string",
    • "attachments": [
      • {
        • "id": "string",
        • "reference_url": "http://example.com",
        • "content_type": "string",
        • "size": "string",
        • "create_time": "string"
        }
      ],
    • "currency_code": "string",
    • "estimate_number": "string",
    • "viewed_by_recipient": true,
    • "estimate_date": "string",
    • "estimate_term": {
      • "term_type": "DUE_ON_RECEIPT",
      • "expiration_date": "string"
      },
    • "metadata": {
      • "created_by": "string",
      • "last_updated_by": "string",
      • "create_time": "string",
      • "last_update_time": "string",
      • "cancelled_by": "string",
      • "last_sent_by": "string",
      • "recipient_view_url": "http://example.com",
      • "invoicer_view_url": "http://example.com",
      • "cancel_time": "string",
      • "first_sent_time": "string",
      • "last_sent_time": "string",
      • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
      }
    },
  • "invoicer": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      },
    • "phones": [
      • {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string",
        • "phone_type": "FAX"
        }
      ],
    • "website": "http://example.com",
    • "tax_id": "string",
    • "additional_notes": "string",
    • "logo_url": "http://example.com",
    • "email_address": "string"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          },
        • "phones": [
          • {
            • "country_code": "str",
            • "national_number": "string",
            • "extension_number": "string",
            • "phone_type": "FAX"
            }
          ],
        • "additional_info": "string",
        • "email_address": "string",
        • "language": "string"
        },
      • "shipping_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          }
        }
      }
    ],
  • "additional_recipients": [
    • "string"
    ],
  • "items": [
    • {
      • "id": "string",
      • "name": "string",
      • "description": "string",
      • "quantity": "string",
      • "unit_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "tax_note": "string",
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "item_date": "string",
      • "discount": {
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "allow_tip": false,
    • "partial_payment": {
      • "allow_partial_payment": false,
      • "minimum_amount_due": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "template_id": "PayPal system template"
    },
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "invoice_discount": {
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "item_discount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "tax_note": "string",
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        },
      • "custom": {
        • "label": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      }
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
estimate_detail
The details of the estimate. Includes estimate number, date and audit metadata.


reference
string  <= 120 characters 
The reference data. Includes a Purchase Order (PO) number.


 
note
string  <= 4000 characters 
A note to the invoice recipient. Also appears on the invoice notification email.


 
terms_and_conditions
string  <= 4000 characters 
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
Array of objects (File Reference)   <= 5 
An array of PayPal IDs for the files that are attached to an invoice.


 
currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
estimate_number
string  [ 1 .. 127 ] characters ^.+$
The invoice number. Default is the number that is auto-incremented number from the last number.


 
viewed_by_recipient
boolean
Represents if the estimate is viewed.


 
estimate_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
object (estimate_payment_term) 
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.


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


 
{
  • "reference": "string",
  • "note": "string",
  • "terms_and_conditions": "string",
  • "memo": "string",
  • "attachments": [
    • {
      • "id": "string",
      • "reference_url": "http://example.com",
      • "content_type": "string",
      • "size": "string",
      • "create_time": "string"
      }
    ],
  • "currency_code": "string",
  • "estimate_number": "string",
  • "viewed_by_recipient": true,
  • "estimate_date": "string",
  • "estimate_term": {
    • "term_type": "DUE_ON_RECEIPT",
    • "expiration_date": "string"
    },
  • "metadata": {
    • "created_by": "string",
    • "last_updated_by": "string",
    • "create_time": "string",
    • "last_update_time": "string",
    • "cancelled_by": "string",
    • "last_sent_by": "string",
    • "recipient_view_url": "http://example.com",
    • "invoicer_view_url": "http://example.com",
    • "cancel_time": "string",
    • "first_sent_time": "string",
    • "last_sent_time": "string",
    • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
    }
}
estimate_free_text_search_fields
Supported estimate free text search fields.


string (estimate_free_text_search_fields)   [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Supported estimate free text search fields.


 Enum Value Description
ESTIMATE_NUMBER
Estimate number.


NOTES
Notes associated with the invoice.


MERCHANT_MEMO
Merchant memo related to the invoice.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the invoice item.


ITEM_TAX_NAME
Tax name associated with the invoice item.


ITEM_DISCOUNT_NAME
Discount name associated with the invoice item.


ESTIMATE_DISCOUNT_NAME
Discount name associated with the estimate.


ALL
Search in all available search fields.


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


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


 Enum Value Description
DUE_ON_RECEIPT
The payment for the invoice is due upon receipt of the invoice.


DUE_ON_DATE_SPECIFIED
The payment for the invoice is due on the date specified in the invoice.


NET_10
The payment for the invoice is due in 10 days.


NET_15
The payment for the invoice is due in 15 days.


NET_30
The payment for the invoice is due in 30 days.


NET_45
The payment for the invoice is due in 45 days.


NET_60
The payment for the invoice is due in 60 days.


NET_90
The payment for the invoice is due in 90 days.


NO_DUE_DATE
The invoice has no payment due date.


 
expiration_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
{
  • "term_type": "DUE_ON_RECEIPT",
  • "expiration_date": "string"
}
estimate_status
Supported estimate status.


string (estimate_status)   [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Supported estimate status.


 Enum Value Description
DRAFT
Draft estimate.


SENT
Estimate sent.


CANCELLED
Estimate cancelled.


SHARED
Estimate shared.


ACCEPTED
Estimate accepted.


INVOICED
Estimate invoiced.


EXPIRED
Estimate expired.


 
"DRAFT"
estimate_suggestion_fields
Supported estimate suggestion fields.


string (estimate_suggestion_fields)   [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Supported estimate suggestion fields.


 Enum Value Description
ESTIMATE_NUMBER
Number associated with it.


NOTES
Notes associated with the estimate.


MERCHANT_MEMO
Merchant memo related to the estimate.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the estimate item.


ALL
This is used to search in all available search fields.


 
"ESTIMATE_NUMBER"
estimates
Suggestion object contains the specified text and the field associated with it.


suggested_text
string  [ 3 .. 800 ] characters ^(?!\s*$).+
Represents the text which has been provided in request.


 
fields
Array of strings (estimate_suggestion_fields)   [ 1 .. 14 ] items  unique 
An array of matched estimate fields.


Items Enum Value Description
ESTIMATE_NUMBER
Number associated with it.


NOTES
Notes associated with the estimate.


MERCHANT_MEMO
Merchant memo related to the estimate.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the estimate item.


ALL
This is used to search in all available search fields.


 
{
  • "suggested_text": "string",
  • "fields": [
    • "ESTIMATE_NUMBER"
    ]
}
File Reference
The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store.


id
string  [ 1 .. 255 ] characters 
The ID of the referenced file.


 
reference_url
string <uri>   [ 1 .. 2000 ] characters 
The reference URL for the file.


 
content_type
size
string^[0-9]+$
The size of the file, in bytes.


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
{
  • "id": "string",
  • "reference_url": "http://example.com",
  • "content_type": "string",
  • "size": "string",
  • "create_time": "string"
}
id
A unique id used to reference the stored discount.


string (id)   [ 1 .. 22 ] characters ^DISC-[A-Z0-9]+$
A unique id used to reference the stored discount.


 
"string"
id
A unique id used to reference the batch task.


string (id)   = 40 characters ^(BAT-)1[0-9A-Z]{3}-[0-9A-Z]{4}-[0-9A-Z]{8}-[...
A unique id used to reference the batch task.


 
"stringstringstringstringstringstringstri"
invoice
The invoice details which includes all information of the invoice like items, billing information.


id
string  <= 30 characters 
The ID of the invoice.


 
parent_id
string  <= 30 characters 
The parent ID to an invoice that defines the group invoice to which the invoice is related.


 
Array of objects (recipient_info)   <= 100 items 
The billing and shipping information. Includes name, email, address, phone and language.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Array of objects (item)   <= 100 items 
An array of invoice line item information.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
status
string (invoice_status) 
The status of the invoice.


 Enum Value Description
DRAFT
The invoice is in draft state. It is not yet sent to the payer.


SENT
The invoice has been sent to the payer. The payment is awaited from the payer.


SCHEDULED
The invoice is scheduled on a future date. It is not yet sent to the payer.


PAID
The payer has paid for the invoice.


MARKED_AS_PAID
The invoice is marked as paid by the invoicer.


CANCELLED
The invoice has been cancelled by the invoicer.


REFUNDED
The invoice has been refunded by the invoicer.


PARTIALLY_PAID
The payer has partially paid for the invoice.


PARTIALLY_REFUNDED
The invoice has been partially refunded by the invoicer.


MARKED_AS_REFUNDED
The invoice is marked as refunded by the invoicer.


UNPAID
The invoicer is yet to receive the payment from the payer for the invoice.


PAYMENT_PENDING
The invoicer is yet to receive the payment for the invoice. It is under pending review.


 
required
object (invoice_detail) 
The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.


 
object (invoicer_info) 
The invoicer business information that appears on the invoice.


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


 
object (amount_summary_detail) 
The invoice amount summary of item total, discount, tax total, and shipping.


 
object (Money) 
The due amount, which is the balance amount outstanding after payments.


 
object (Money) 
The amount paid by the payer as gratuity to the invoicer.


 
object (payments) 
An array of payments registered against the invoice.


 
object (refunds) 
The invoicing refund details. Includes the refund type, date, amount, and method.


 
{
  • "id": "string",
  • "parent_id": "string",
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          },
        • "phones": [
          • {
            • "country_code": "str",
            • "national_number": "string",
            • "extension_number": "string",
            • "phone_type": "FAX"
            }
          ],
        • "additional_info": "string",
        • "email_address": "string",
        • "language": "string"
        },
      • "shipping_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          }
        }
      }
    ],
  • "additional_recipients": [
    • "string"
    ],
  • "items": [
    • {
      • "id": "string",
      • "name": "string",
      • "description": "string",
      • "quantity": "string",
      • "unit_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "tax_note": "string",
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "item_date": "string",
      • "discount": {
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "status": "DRAFT",
  • "detail": {
    • "reference": "string",
    • "note": "string",
    • "terms_and_conditions": "string",
    • "memo": "string",
    • "attachments": [
      • {
        • "id": "string",
        • "reference_url": "http://example.com",
        • "content_type": "string",
        • "size": "string",
        • "create_time": "string"
        }
      ],
    • "currency_code": "string",
    • "invoice_number": "string",
    • "invoice_date": "string",
    • "payment_term": {
      • "term_type": "DUE_ON_RECEIPT",
      • "due_date": "string"
      },
    • "metadata": {
      • "created_by": "string",
      • "last_updated_by": "string",
      • "create_time": "string",
      • "last_update_time": "string",
      • "cancelled_by": "string",
      • "last_sent_by": "string",
      • "recipient_view_url": "http://example.com",
      • "invoicer_view_url": "http://example.com",
      • "cancel_time": "string",
      • "first_sent_time": "string",
      • "last_sent_time": "string",
      • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
      }
    },
  • "invoicer": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      },
    • "phones": [
      • {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string",
        • "phone_type": "FAX"
        }
      ],
    • "website": "http://example.com",
    • "tax_id": "string",
    • "additional_notes": "string",
    • "logo_url": "http://example.com",
    • "email_address": "string"
    },
  • "configuration": {
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "allow_tip": false,
    • "partial_payment": {
      • "allow_partial_payment": false,
      • "minimum_amount_due": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "template_id": "PayPal system template"
    },
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "invoice_discount": {
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "item_discount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "tax_note": "string",
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        },
      • "custom": {
        • "label": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      }
    },
  • "due_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "gratuity": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "payments": {
    • "transactions": [
      • {
        • "payment_id": "string",
        • "note": "string",
        • "type": "PAYPAL",
        • "payment_date": "string",
        • "method": "BANK_TRANSFER",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "shipping_info": {
          • "business_name": "string",
          • "name": {
            • "prefix": "string",
            • "given_name": "string",
            • "surname": "string",
            • "middle_name": "string",
            • "suffix": "string",
            • "alternate_full_name": "string",
            • "full_name": "string"
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "address_line_3": "string",
            • "admin_area_4": "string",
            • "admin_area_3": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st",
            • "address_details": {
              • "street_number": "string",
              • "street_name": "string",
              • "street_type": "string",
              • "delivery_service": "string",
              • "building_name": "string",
              • "sub_building": "string"
              }
            }
          }
        }
      ],
    • "paid_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "refunds": {
    • "transactions": [
      • {
        • "refund_id": "string",
        • "type": "PAYPAL",
        • "refund_date": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "method": "BANK_TRANSFER"
        }
      ],
    • "refund_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}
Invoice Number
The invoice number.


invoice_number
string  <= 25 characters 
The invoice number. If you omit this value, the default is the auto-incremented number from the last number.


 
{
  • "invoice_number": "string"
}
invoice_creation_flow
The frequency at which the invoice is sent:
  • Multiple recipient. Sent to multiple recipients.
  • Batch. Sent in a batch.
  • Regular single. Sent one time to a single recipient.


string (invoice_creation_flow) 
The frequency at which the invoice is sent:
  • Multiple recipient. Sent to multiple recipients.
  • Batch. Sent in a batch.
  • Regular single. Sent one time to a single recipient.


 Enum Value Description
MULTIPLE_RECIPIENTS_GROUP
The invoice sent to multiple recipients.


BATCH
The invoice sent as a batch.


REGULAR_SINGLE
The regular invoice sent to single recipient.


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


reference
string  <= 120 characters 
The reference data. Includes a Purchase Order (PO) number.


 
note
string  <= 4000 characters 
A note to the invoice recipient. Also appears on the invoice notification email.


 
terms_and_conditions
string  <= 4000 characters 
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
Array of objects (File Reference)   <= 5 
An array of PayPal IDs for the files that are attached to an invoice.


 
currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
invoice_number
string  <= 25 characters 
The invoice number. Default is the number that is auto-incremented number from the last number.


 
invoice_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
object (invoice_payment_term) 
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.


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


 
{
  • "reference": "string",
  • "note": "string",
  • "terms_and_conditions": "string",
  • "memo": "string",
  • "attachments": [
    • {
      • "id": "string",
      • "reference_url": "http://example.com",
      • "content_type": "string",
      • "size": "string",
      • "create_time": "string"
      }
    ],
  • "currency_code": "string",
  • "invoice_number": "string",
  • "invoice_date": "string",
  • "payment_term": {
    • "term_type": "DUE_ON_RECEIPT",
    • "due_date": "string"
    },
  • "metadata": {
    • "created_by": "string",
    • "last_updated_by": "string",
    • "create_time": "string",
    • "last_update_time": "string",
    • "cancelled_by": "string",
    • "last_sent_by": "string",
    • "recipient_view_url": "http://example.com",
    • "invoicer_view_url": "http://example.com",
    • "cancel_time": "string",
    • "first_sent_time": "string",
    • "last_sent_time": "string",
    • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
    }
}
invoice_free_text_search_fields
Supported invoice free text search fields.


string (invoice_free_text_search_fields)   [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Supported invoice free text search fields.


 Enum Value Description
INVOICE_NUMBER
Invoice number.


NOTES
Notes associated with the invoice.


MERCHANT_MEMO
Merchant memo related to the invoice.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the invoice item.


ITEM_TAX_NAME
Tax name associated with the invoice item.


ITEM_DISCOUNT_NAME
Discount name associated with the invoice item.


TRANSACTION_ID
Transaction ID associated with the invoice payment.


GROUP_ID
Group ID associated with the invoice.


INVOICE_DISCOUNT_NAME
Discount name associated with the invoice.


ALL
Search in all available search fields (except GROUP_ID).


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


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


 Enum Value Description
DUE_ON_RECEIPT
The payment for the invoice is due upon receipt of the invoice.


DUE_ON_DATE_SPECIFIED
The payment for the invoice is due on the date specified in the invoice.


NET_10
The payment for the invoice is due in 10 days.


NET_15
The payment for the invoice is due in 15 days.


NET_30
The payment for the invoice is due in 30 days.


NET_45
The payment for the invoice is due in 45 days.


NET_60
The payment for the invoice is due in 60 days.


NET_90
The payment for the invoice is due in 90 days.


NO_DUE_DATE
The invoice has no payment due date.


 
due_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
{
  • "term_type": "DUE_ON_RECEIPT",
  • "due_date": "string"
}
invoice_status
The status of the invoice.


string (invoice_status) 
The status of the invoice.


 Enum Value Description
DRAFT
The invoice is in draft state. It is not yet sent to the payer.


SENT
The invoice has been sent to the payer. The payment is awaited from the payer.


SCHEDULED
The invoice is scheduled on a future date. It is not yet sent to the payer.


PAID
The payer has paid for the invoice.


MARKED_AS_PAID
The invoice is marked as paid by the invoicer.


CANCELLED
The invoice has been cancelled by the invoicer.


REFUNDED
The invoice has been refunded by the invoicer.


PARTIALLY_PAID
The payer has partially paid for the invoice.


PARTIALLY_REFUNDED
The invoice has been partially refunded by the invoicer.


MARKED_AS_REFUNDED
The invoice is marked as refunded by the invoicer.


UNPAID
The invoicer is yet to receive the payment from the payer for the invoice.


PAYMENT_PENDING
The invoicer is yet to receive the payment for the invoice. It is under pending review.


 
"DRAFT"
invoice_suggestion_fields
Supported invoice suggestion fields.


string (invoice_suggestion_fields)   [ 1 .. 255 ] characters ^[A-Z0-9_]+$
Supported invoice suggestion fields.


 Enum Value Description
INVOICE_NUMBER
Number associated with it.


NOTES
Notes associated with the invoice.


MERCHANT_MEMO
Merchant memo related to the invoice.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the invoice item.


TRANSACTION_ID
Transaction ID associated with the invoice payment.


ALL
This is used to search in all available search fields.


 
"INVOICE_NUMBER"
invoicer_info
The invoicer business information that appears on the invoice.


business_name
string  <= 300 characters 
Required. The business name of the party.


 
object (Name) 
The name of the party.


 
object (Portable Postal Address (Medium-Grained)) 
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


 
Array of objects (phone_detail) 
An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.


 
website
string <uri>   <= 2048 characters 
The invoicer's website.


 
tax_id
string  <= 100 characters 
The invoicer's tax ID.


 
additional_notes
string  <= 400 characters 
Any additional information. Includes business hours.


 
logo_url
string <uri>   <= 2000 characters 
The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.


 
email_address
string (restrictive_email_address)   [ 3 .. 254 ] characters ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(...
The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part. 
  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
{
  • "business_name": "string",
  • "name": {
    • "prefix": "string",
    • "given_name": "string",
    • "surname": "string",
    • "middle_name": "string",
    • "suffix": "string",
    • "alternate_full_name": "string",
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      }
    },
  • "phones": [
    • {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string",
      • "phone_type": "FAX"
      }
    ],
  • "website": "http://example.com",
  • "tax_id": "string",
  • "additional_notes": "string",
  • "logo_url": "http://example.com",
  • "email_address": "string"
}
invoices
An array of merchant invoices. Includes the total invoices count and HATEOAS links for navigation.


total_pages
integer
The total number of pages that are available for the search criteria. 
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next


 
total_items
integer
The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of total_items is constant. The value MAY change from one request to the next.


 
Array of objects (invoice) 
The list of invoices that match the search criteria.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "total_pages": 0,
  • "total_items": 0,
  • "items": [
    • {
      • "id": "string",
      • "parent_id": "string",
      • "primary_recipients": [
        • {
          • "billing_info": {
            • "business_name": "string",
            • "name": {
              • "prefix": "string",
              • "given_name": "string",
              • "surname": "string",
              • "middle_name": "string",
              • "suffix": "string",
              • "alternate_full_name": "string",
              • "full_name": "string"
              },
            • "address": {
              • "address_line_1": "string",
              • "address_line_2": "string",
              • "address_line_3": "string",
              • "admin_area_4": "string",
              • "admin_area_3": "string",
              • "admin_area_2": "string",
              • "admin_area_1": "string",
              • "postal_code": "string",
              • "country_code": "st",
              • "address_details": {
                • "street_number": null,
                • "street_name": null,
                • "street_type": null,
                • "delivery_service": null,
                • "building_name": null,
                • "sub_building": null
                }
              },
            • "phones": [
              • {
                • "country_code": null,
                • "national_number": null,
                • "extension_number": null,
                • "phone_type": null
                }
              ],
            • "additional_info": "string",
            • "email_address": "string",
            • "language": "string"
            },
          • "shipping_info": {
            • "business_name": "string",
            • "name": {
              • "prefix": "string",
              • "given_name": "string",
              • "surname": "string",
              • "middle_name": "string",
              • "suffix": "string",
              • "alternate_full_name": "string",
              • "full_name": "string"
              },
            • "address": {
              • "address_line_1": "string",
              • "address_line_2": "string",
              • "address_line_3": "string",
              • "admin_area_4": "string",
              • "admin_area_3": "string",
              • "admin_area_2": "string",
              • "admin_area_1": "string",
              • "postal_code": "string",
              • "country_code": "st",
              • "address_details": {
                • "street_number": null,
                • "street_name": null,
                • "street_type": null,
                • "delivery_service": null,
                • "building_name": null,
                • "sub_building": null
                }
              }
            }
          }
        ],
      • "additional_recipients": [
        • "string"
        ],
      • "items": [
        • {
          • "id": "string",
          • "name": "string",
          • "description": "string",
          • "quantity": "string",
          • "unit_amount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "tax": {
            • "name": "string",
            • "tax_note": "string",
            • "percent": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            },
          • "item_date": "string",
          • "discount": {
            • "percent": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            },
          • "unit_of_measure": "QUANTITY"
          }
        ],
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "status": "DRAFT",
      • "detail": {
        • "reference": "string",
        • "note": "string",
        • "terms_and_conditions": "string",
        • "memo": "string",
        • "attachments": [
          • {
            • "id": "string",
            • "reference_url": "http://example.com",
            • "content_type": "string",
            • "size": "string",
            • "create_time": "string"
            }
          ],
        • "currency_code": "string",
        • "invoice_number": "string",
        • "invoice_date": "string",
        • "payment_term": {
          • "term_type": "DUE_ON_RECEIPT",
          • "due_date": "string"
          },
        • "metadata": {
          • "created_by": "string",
          • "last_updated_by": "string",
          • "create_time": "string",
          • "last_update_time": "string",
          • "cancelled_by": "string",
          • "last_sent_by": "string",
          • "recipient_view_url": "http://example.com",
          • "invoicer_view_url": "http://example.com",
          • "cancel_time": "string",
          • "first_sent_time": "string",
          • "last_sent_time": "string",
          • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
          }
        },
      • "invoicer": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          },
        • "phones": [
          • {
            • "country_code": "str",
            • "national_number": "string",
            • "extension_number": "string",
            • "phone_type": "FAX"
            }
          ],
        • "website": "http://example.com",
        • "tax_id": "string",
        • "additional_notes": "string",
        • "logo_url": "http://example.com",
        • "email_address": "string"
        },
      • "configuration": {
        • "tax_calculated_after_discount": true,
        • "tax_inclusive": false,
        • "allow_tip": false,
        • "partial_payment": {
          • "allow_partial_payment": false,
          • "minimum_amount_due": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "template_id": "PayPal system template"
        },
      • "amount": {
        • "currency_code": "str",
        • "value": "string",
        • "breakdown": {
          • "item_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "discount": {
            • "invoice_discount": {
              • "percent": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              },
            • "item_discount": {
              • "currency_code": "str",
              • "value": "string"
              }
            },
          • "tax_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "shipping": {
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "tax": {
              • "name": "string",
              • "tax_note": "string",
              • "percent": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            },
          • "custom": {
            • "label": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          }
        },
      • "due_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "gratuity": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payments": {
        • "transactions": [
          • {
            • "payment_id": "string",
            • "note": "string",
            • "type": "PAYPAL",
            • "payment_date": "string",
            • "method": "BANK_TRANSFER",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "shipping_info": {
              • "business_name": "string",
              • "name": {
                • "prefix": null,
                • "given_name": null,
                • "surname": null,
                • "middle_name": null,
                • "suffix": null,
                • "alternate_full_name": null,
                • "full_name": null
                },
              • "address": {
                • "address_line_1": null,
                • "address_line_2": null,
                • "address_line_3": null,
                • "admin_area_4": null,
                • "admin_area_3": null,
                • "admin_area_2": null,
                • "admin_area_1": null,
                • "postal_code": null,
                • "country_code": null,
                • "address_details": { }
                }
              }
            }
          ],
        • "paid_amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "refunds": {
        • "transactions": [
          • {
            • "refund_id": "string",
            • "type": "PAYPAL",
            • "refund_date": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "method": "BANK_TRANSFER"
            }
          ],
        • "refund_amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
invoices
Suggestion object contains the specified text and the field associated with it.


suggested_text
string  [ 3 .. 800 ] characters ^(?!\s*$).+
Represents the text which has been provided in request.


 
fields
Array of strings (invoice_suggestion_fields)   [ 1 .. 14 ] items  unique 
An array of matched invoice fields.


Items Enum Value Description
INVOICE_NUMBER
Number associated with it.


NOTES
Notes associated with the invoice.


MERCHANT_MEMO
Merchant memo related to the invoice.


PAYER_REFERENCE_INFO
Payer's reference information.


BILLING_EMAIL
Email address associated with billing.


BILLING_NAME
Name associated with billing.


BILLING_BUSINESS_NAME
Business name associated with billing.


BILLING_PHONE_NUMBER
Phone number associated with billing.


SHIPPING_EMAIL
Email address associated with shipping.


SHIPPING_NAME
Name associated with shipping.


SHIPPING_BUSINESS_NAME
Business name associated with shipping.


SHIPPING_PHONE_NUMBER
Phone number associated with shipping.


ITEM_NAME
Name of the invoice item.


TRANSACTION_ID
Transaction ID associated with the invoice payment.


ALL
This is used to search in all available search fields.


 
{
  • "suggested_text": "string",
  • "fields": [
    • "INVOICE_NUMBER"
    ]
}
item
An array of invoice line item information. The maximum items for an invoice is 100.


id
string  <= 22 characters 
The ID of the invoice line item.


 
name
required
string  <= 200 characters 
The item name for the invoice line item.


 
description
string  <= 1000 characters 
The item description for the invoice line item.


 
quantity
required
string  [ 0 .. 14 ] characters 
The quantity of the item that the invoicer provides to the payer. Value is from -1000000 to 1000000. Supports up to five decimal places.


 
required
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (tax) 
The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total.


 
item_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


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


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


 Enum Value Description
QUANTITY
The unit of measure is quantity. This invoice template is typically used for physical goods.


HOURS
The unit of measure is hours. This invoice template is typically used for services.


AMOUNT
The unit of measure is amount. This invoice template is typically used when only amount is required.


 
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "quantity": "string",
  • "unit_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "tax_note": "string",
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "item_date": "string",
  • "discount": {
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "unit_of_measure": "QUANTITY"
}
language
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.


string <ppaas_common_language_v3>  (language)   [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.


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


created_by
string
The email address of the account that created the resource.


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


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
last_update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
cancelled_by
string
The actor who canceled the resource.


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


 
recipient_view_url
string <uri> 
The URL for the invoice payer view hosted on paypal.com.


 
invoicer_view_url
string <uri> 
The URL for the invoice merchant view hosted on paypal.com.


 
cancel_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
first_sent_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
last_sent_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
created_by_flow
string (invoice_creation_flow) 
The flow variation that created this invoice.


 Enum Value Description
MULTIPLE_RECIPIENTS_GROUP
The invoice sent to multiple recipients.


BATCH
The invoice sent as a batch.


REGULAR_SINGLE
The regular invoice sent to single recipient.


 
{
  • "created_by": "string",
  • "last_updated_by": "string",
  • "create_time": "string",
  • "last_update_time": "string",
  • "cancelled_by": "string",
  • "last_sent_by": "string",
  • "recipient_view_url": "http://example.com",
  • "invoicer_view_url": "http://example.com",
  • "cancel_time": "string",
  • "first_sent_time": "string",
  • "last_sent_time": "string",
  • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
}
Money
The currency and amount for a financial transaction, such as a balance or payment due.


currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
value
required
string  <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be:
  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.


 
{
  • "currency_code": "str",
  • "value": "string"
}
Name
The name of the party.


prefix
string  <= 140 characters 
The prefix, or title, to the party's name.


 
given_name
string  <= 140 characters 
When the party is a person, the party's given, or first, name.


 
surname
string  <= 140 characters 
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.


 
middle_name
string  <= 140 characters 
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.


 
suffix
string  <= 140 characters 
The suffix for the party's name.


 
alternate_full_name
string  <= 300 characters 
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.


 
full_name
string  <= 300 characters 
When the party is a person, the party's full name.


 
{
  • "prefix": "string",
  • "given_name": "string",
  • "surname": "string",
  • "middle_name": "string",
  • "suffix": "string",
  • "alternate_full_name": "string",
  • "full_name": "string"
}
notification
The email or SMS notification to send to the invoicer or payer on sending an invoice.


subject
string  <= 4000 characters 
The subject of the email that is sent as a notification to the recipient.


 
note
string  <= 4000 characters 
A note to the payer.


 
send_to_invoicer
boolean
 Default:  false
Indicates whether to send a copy of the email to the merchant.


 
send_to_recipient
boolean
 Default:  true
Indicates whether to send a copy of the email to the recipient.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
{
  • "subject": "string",
  • "note": "string",
  • "send_to_invoicer": false,
  • "send_to_recipient": true,
  • "additional_recipients": [
    • "string"
    ]
}
partial_payment
The partial payment details. Includes the minimum amount that the invoicer expects from the payer.


allow_partial_payment
boolean
 Default:  false
Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
Note: This feature is not available for users in India, Brazil, or Israel.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "allow_partial_payment": false,
  • "minimum_amount_due": {
    • "currency_code": "str",
    • "value": "string"
    }
}
Patch
The JSON patch object to apply partial updates to resources.


op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
any (Patch Value) 
The value to apply. The remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
{
  • "op": "add",
  • "path": "string",
  • "value": null,
  • "from": "string"
}
payment_detail
The payment details of the invoice. Includes payment type, method, date, discount, and transaction type.


payment_id
string  <= 22 characters 
The ID for a PayPal payment transaction. Required for the PAYPAL payment type.


 
note
string  <= 2000 characters 
A note associated with an external cash or check payment.


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


 Enum Value Description
PAYPAL
The payment type is PayPal.


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


 
payment_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
method
required
string (payment_method) 
The payment mode or method through which the invoicer can accept the payment.


 Enum Value Description
BANK_TRANSFER
Payments can be received through bank transfers.


CASH
Payments can be received as cash.


CHECK
Payments can be received as check.


CREDIT_CARD
Payments can be received through credit card payments.


DEBIT_CARD
Payments can be received through debit card payments.


PAYPAL
Payments can be received through paypal payments.


WIRE_TRANSFER
Payments can be received through wire transfer.


OTHER
Payments can be received through other modes.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (contact_information) 
The contact information of the user. Includes name and address.


 
{
  • "payment_id": "string",
  • "note": "string",
  • "type": "PAYPAL",
  • "payment_date": "string",
  • "method": "BANK_TRANSFER",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_info": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      }
    }
}
payment_method
The payment mode or method through which the invoicer can accept the payments.


string (payment_method) 
The payment mode or method through which the invoicer can accept the payments.


 Enum Value Description
BANK_TRANSFER
Payments can be received through bank transfers.


CASH
Payments can be received as cash.


CHECK
Payments can be received as check.


CREDIT_CARD
Payments can be received through credit card payments.


DEBIT_CARD
Payments can be received through debit card payments.


PAYPAL
Payments can be received through paypal payments.


WIRE_TRANSFER
Payments can be received through wire transfer.


OTHER
Payments can be received through other modes.


 
"BANK_TRANSFER"
payment_reference
The reference to the payment detail.


payment_id
string
The ID for the invoice payment.


 
{
  • "payment_id": "string"
}
payment_term
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.


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


 Enum Value Description
DUE_ON_RECEIPT
The payment for the invoice is due upon receipt of the invoice.


DUE_ON_DATE_SPECIFIED
The payment for the invoice is due on the date specified in the invoice.


NET_10
The payment for the invoice is due in 10 days.


NET_15
The payment for the invoice is due in 15 days.


NET_30
The payment for the invoice is due in 30 days.


NET_45
The payment for the invoice is due in 45 days.


NET_60
The payment for the invoice is due in 60 days.


NET_90
The payment for the invoice is due in 90 days.


NO_DUE_DATE
The invoice has no payment due date.


 
{
  • "term_type": "DUE_ON_RECEIPT"
}
payment_term_type
The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.


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


 Enum Value Description
DUE_ON_RECEIPT
The payment for the invoice is due upon receipt of the invoice.


DUE_ON_DATE_SPECIFIED
The payment for the invoice is due on the date specified in the invoice.


NET_10
The payment for the invoice is due in 10 days.


NET_15
The payment for the invoice is due in 15 days.


NET_30
The payment for the invoice is due in 30 days.


NET_45
The payment for the invoice is due in 45 days.


NET_60
The payment for the invoice is due in 60 days.


NET_90
The payment for the invoice is due in 90 days.


NO_DUE_DATE
The invoice has no payment due date.


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


string (payment_type) 
The payment type. Can be PayPal or an external payment. Includes cash or a check.


 Enum Value Description
PAYPAL
The payment type is PayPal.


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


 
"PAYPAL"
payments
An array of payments registered against the invoice.


Array of objects (payment_detail)   <= 100 items 
An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "transactions": [
    • {
      • "payment_id": "string",
      • "note": "string",
      • "type": "PAYPAL",
      • "payment_date": "string",
      • "method": "BANK_TRANSFER",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          }
        }
      }
    ],
  • "paid_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
PayPal Account Identifier
The account identifier for a PayPal account.


string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The account identifier for a PayPal account.


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


string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.


 
"string"
Phone
The phone number, in its canonical international E.164 numbering plan format.


country_code
required
string  [ 1 .. 3 ] characters ^[0-9]{1,3}?$
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).


 
national_number
required
string  [ 1 .. 14 ] characters ^[0-9]{1,14}?$
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).


 
extension_number
string  [ 1 .. 15 ] characters ^[0-9]{1,15}?$
The extension number.


 
{
  • "country_code": "str",
  • "national_number": "string",
  • "extension_number": "string"
}
Phone
The phone number, in its canonical international E.164 numbering plan format.


national_number
required
string  [ 1 .. 14 ] characters ^[0-9]{1,14}?$
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).


 
{
  • "national_number": "string"
}
Phone Type
The phone type.


string (Phone Type) 
The phone type.


 Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"  
"FAX"
Phone Type
The phone type.


string (Phone Type) 
The phone type.


 Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"  
"FAX"
phone_detail
The phone details. Includes the phone number and type.


country_code
required
string  [ 1 .. 3 ] characters ^[0-9]{1,3}?$
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).


 
national_number
required
string  [ 1 .. 14 ] characters ^[0-9]{1,14}?$
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).


 
extension_number
string  [ 1 .. 15 ] characters ^[0-9]{1,15}?$
The extension number.


 
phone_type
required
string (Phone Type) 
The phone type.


 Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"  
{
  • "country_code": "str",
  • "national_number": "string",
  • "extension_number": "string",
  • "phone_type": "FAX"
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
address_line_3
string  <= 100 characters 
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.


 
admin_area_4
string  <= 100 characters 
The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
  • The postal sorting code for Guernsey and many French territories, such as French Guiana.
  • The fine-grained administrative levels in China.


 
admin_area_3
string  <= 100 characters 
A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
  • Brazil. Suburb, bairro, or neighborhood.
  • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
  • UK. A county.
  • US. A state.
  • Canada. A province.
  • Japan. A prefecture.
  • Switzerland. A kanton.


 
postal_code
string  <= 60 characters 
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.


 
country_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.


 
object (Address Details) 
The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "address_line_3": "string",
  • "admin_area_4": "string",
  • "admin_area_3": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st",
  • "address_details": {
    • "street_number": "string",
    • "street_name": "string",
    • "street_type": "string",
    • "delivery_service": "string",
    • "building_name": "string",
    • "sub_building": "string"
    }
}
qr_config
The configuration for a QR code.


width
integer  [ 150 .. 500 ] 
 Default:  500
The width, in pixels, of the QR code image. Value is from 150 to 500.


 
height
integer  [ 150 .. 500 ] 
 Default:  500
The height, in pixels, of the QR code image. Value is from 150 to 500.


 
action
string  <= 7 characters (?i)^(pay|details)$
 Default:  "pay"
The type of URL for which to generate a QR code. Valid values are pay and details.


 
{
  • "width": 500,
  • "height": 500,
  • "action": "pay"
}
recipient_info
The billing and shipping information. Includes name, email, address, phone, and language.


object (billing_info) 
The billing information of the invoice recipient. Includes name, address, email, phone, and language.


 
object (contact_information) 
The contact information of the user. Includes name and address.


 
{
  • "billing_info": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      },
    • "phones": [
      • {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string",
        • "phone_type": "FAX"
        }
      ],
    • "additional_info": "string",
    • "email_address": "string",
    • "language": "string"
    },
  • "shipping_info": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      }
    }
}
refund_detail
The refund details of the invoice. Includes the refund type, date, amount, and method.


refund_id
string  <= 22 characters 
The ID for a PayPal payment transaction. Required for the PAYPAL payment type.


 
type
string (payment_type) 
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.


 Enum Value Description
PAYPAL
The payment type is PayPal.


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


 
refund_date
string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
method
required
string (payment_method) 
The payment mode or method through which the invoicer can accept the payments.


 Enum Value Description
BANK_TRANSFER
Payments can be received through bank transfers.


CASH
Payments can be received as cash.


CHECK
Payments can be received as check.


CREDIT_CARD
Payments can be received through credit card payments.


DEBIT_CARD
Payments can be received through debit card payments.


PAYPAL
Payments can be received through paypal payments.


WIRE_TRANSFER
Payments can be received through wire transfer.


OTHER
Payments can be received through other modes.


 
{
  • "refund_id": "string",
  • "type": "PAYPAL",
  • "refund_date": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "method": "BANK_TRANSFER"
}
refund_reference
The reference to the refund payment detail.


refund_id
string
The ID of the refund of an invoice payment.


 
{
  • "refund_id": "string"
}
refunds
The invoicing refund details. Includes the refund type, date, amount, and method.


Array of objects (refund_detail)   <= 100 items 
An array of refund details for the invoice. Includes the refund type, date, amount, and method.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "transactions": [
    • {
      • "refund_id": "string",
      • "type": "PAYPAL",
      • "refund_date": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "method": "BANK_TRANSFER"
      }
    ],
  • "refund_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
restrictive_email_address
The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part. 
  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


string (restrictive_email_address)   [ 3 .. 254 ] characters ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(...
The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part. 
  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
"string"
Search filters properties.
Search filters - to retrieve invoices. 
Note:This API currently supports only one criterion for range queries, so specify only one of the following criteria: invoice_date_range, due_date_range, or payment_date_range.


currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
status
Array of strings (invoice_status)   [ 1 .. 5 ] items  unique 
An array of invoice status.


Items Enum Value Description
DRAFT
The invoice is in draft state. It is not yet sent to the payer.


SENT
The invoice has been sent to the payer. The payment is awaited from the payer.


SCHEDULED
The invoice is scheduled on a future date. It is not yet sent to the payer.


PAID
The payer has paid for the invoice.


MARKED_AS_PAID
The invoice is marked as paid by the invoicer.


CANCELLED
The invoice has been cancelled by the invoicer.


REFUNDED
The invoice has been refunded by the invoicer.


PARTIALLY_PAID
The payer has partially paid for the invoice.


PARTIALLY_REFUNDED
The invoice has been partially refunded by the invoicer.


MARKED_AS_REFUNDED
The invoice is marked as refunded by the invoicer.


UNPAID
The invoicer is yet to receive the payment from the payer for the invoice.


PAYMENT_PENDING
The invoicer is yet to receive the payment for the invoice. It is under pending review.


 
archived
boolean
Indicates whether to list merchant-archived invoices in the response. If 'true', the response lists only merchant-archived invoices. If 'false', the response lists only unarchived invoices. If 'null', the response lists all invoices.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (amount_range) 
The amount range.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
{
  • "currency_code": "str",
  • "status": [
    • "DRAFT"
    ],
  • "archived": true,
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "invoice_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "due_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "payment_date_range": {
    • "start": "string",
    • "end": "string"
    }
}
Search filters properties.
Search filters - to retrieve estimates.


currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
status
Array of strings (estimate_status)   [ 1 .. 5 ] items  unique 
An array of estimate status.


Items Enum Value Description
DRAFT
Draft estimate.


SENT
Estimate sent.


CANCELLED
Estimate cancelled.


SHARED
Estimate shared.


ACCEPTED
Estimate accepted.


INVOICED
Estimate invoiced.


EXPIRED
Estimate expired.


 
archived
boolean
Indicates whether to list merchant-archived invoices in the response. If 'true', the response lists only merchant-archived invoices. If 'false', the response lists only unarchived invoices. If 'null', the response lists all invoices.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (amount_range) 
The amount range.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
{
  • "currency_code": "str",
  • "status": [
    • "DRAFT"
    ],
  • "archived": true,
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "estimate_date_range": {
    • "start": "string",
    • "end": "string"
    }
}
search_data
The invoice search parameters.


recipient_email
string  <= 254 characters 
Filters the search by the email address.


 
recipient_first_name
string  <= 140 characters 
Filters the search by the recipient first name.


 
recipient_last_name
string  <= 140 characters 
Filters the search by the recipient last name.


 
recipient_business_name
string  <= 300 characters 
Filters the search by the recipient business name.


 
invoice_number
string  <= 25 characters 
Filters the search by the invoice number.


 
status
Array of strings (invoice_status)   <= 5 items 
An array of status values.


Items Enum Value Description
DRAFT
The invoice is in draft state. It is not yet sent to the payer.


SENT
The invoice has been sent to the payer. The payment is awaited from the payer.


SCHEDULED
The invoice is scheduled on a future date. It is not yet sent to the payer.


PAID
The payer has paid for the invoice.


MARKED_AS_PAID
The invoice is marked as paid by the invoicer.


CANCELLED
The invoice has been cancelled by the invoicer.


REFUNDED
The invoice has been refunded by the invoicer.


PARTIALLY_PAID
The payer has partially paid for the invoice.


PARTIALLY_REFUNDED
The invoice has been partially refunded by the invoicer.


MARKED_AS_REFUNDED
The invoice is marked as refunded by the invoicer.


UNPAID
The invoicer is yet to receive the payment from the payer for the invoice.


PAYMENT_PENDING
The invoicer is yet to receive the payment for the invoice. It is under pending review.


 
reference
string  <= 120 characters 
The reference data, such as a PO number.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
archived
boolean
Indicates whether to list merchant-archived invoices in the response. Value is:
  • true. Response lists only merchant-archived invoices.
  • false. Response lists only unarchived invoices.
  • null. Response lists all invoices.


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


 
currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
object (amount_range) 
The amount range.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (date_range) 
The date range. Filters invoices by creation date, invoice date, due date, and payment date.


 
object (Date and Time Range) 
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.


 
{
  • "recipient_email": "string",
  • "recipient_first_name": "string",
  • "recipient_last_name": "string",
  • "recipient_business_name": "string",
  • "invoice_number": "string",
  • "status": [
    • "DRAFT"
    ],
  • "reference": "string",
  • "memo": "string",
  • "payment_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "archived": true,
  • "fields": [
    • "string"
    ],
  • "currency_code": "string",
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "invoice_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "due_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    }
}
shipping_cost
The shipping fee for all items. Includes tax on shipping.


object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
object (tax) 
The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total.


 
{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "tax_note": "string",
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}
stored_discount
The details about the stored discount.


id
string (id)   = 40 characters ^(BAT-)1[0-9A-Z]{3}-[0-9A-Z]{4}-[0-9A-Z]{8}-[...
A unique id used to reference the batch task.


 
name
required
string  [ 1 .. 40 ] characters ^[a-zA-Z0-9\s]+$
Represents the name of the stored discount.


 
value
required
string  [ 1 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
Represents the value of the stored discount it can be a percentage or absolute value. In case of absolute value, which might be:
  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.


 
type
required
string (type)   [ 1 .. 20 ] characters ^[A-Z0-9_]*$
Type of the stored discount. Used to determine wheather its percentage or absolute currency value.


 Enum Value Description
PERCENT
Percentage of discount used in invoice item or in an invoice.


AMOUNT
An absolute value of discount used in invoice item or in an invoice based on the currency in invoice.


 
active
boolean
Indicates whether given stored discount is active or not.


 
created_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
Indicates time of stored discount creation.


 
updated_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
Indicates time of stored discount updation.


 
{
  • "id": "stringstringstringstringstringstringstri",
  • "name": "string",
  • "value": "string",
  • "type": "PERCENT",
  • "active": true,
  • "created_time": "stringstringstringst",
  • "updated_time": "stringstringstringst"
}
task_type
Task type of the batch task. Used to determine the batch operation/logic to be performed.


string (task_type)   [ 1 .. 50 ] characters ^[A-Z0-9_]*$
Task type of the batch task. Used to determine the batch operation/logic to be performed.


 Enum Value Description
RISK_LIMIT_RECENT
Task for processing recent records for the account in Invoicing.


RISK_LIMIT_FULL
Task for processing all records in Invoicing.


 
"RISK_LIMIT_RECENT"
tax
The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total.


name
required
string  <= 100 characters 
The name of the tax applied on the invoice items.


 
tax_note
string  [ 0 .. 40 ] characters ^[\s\S]*$
The tax note used to track the tax related data.


 
percent
required
string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "name": "string",
  • "tax_note": "string",
  • "percent": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
template
The template with invoice details to load with all captured fields.


id
string  <= 30 characters 
The ID of the template.


 
name
string  [ 1 .. 500 ] characters 
The template name.
Note: The template name must be unique.


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


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


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
object (template_info) 
The template details. Includes invoicer business information, invoice recipients, items, and configuration.


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


 
unit_of_measure
string (unit_of_measure) 
The unit of measure for the invoiced item.


 Enum Value Description
QUANTITY
The unit of measure is quantity. This invoice template is typically used for physical goods.


HOURS
The unit of measure is hours. This invoice template is typically used for services.


AMOUNT
The unit of measure is amount. This invoice template is typically used when only amount is required.


 
{
  • "id": "string",
  • "name": "string",
  • "default_template": true,
  • "standard_template": true,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "template_info": {
    • "primary_recipients": [
      • {
        • "billing_info": {
          • "business_name": "string",
          • "name": {
            • "prefix": "string",
            • "given_name": "string",
            • "surname": "string",
            • "middle_name": "string",
            • "suffix": "string",
            • "alternate_full_name": "string",
            • "full_name": "string"
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "address_line_3": "string",
            • "admin_area_4": "string",
            • "admin_area_3": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st",
            • "address_details": {
              • "street_number": "string",
              • "street_name": "string",
              • "street_type": "string",
              • "delivery_service": "string",
              • "building_name": "string",
              • "sub_building": "string"
              }
            },
          • "phones": [
            • {
              • "country_code": "str",
              • "national_number": "string",
              • "extension_number": "string",
              • "phone_type": "FAX"
              }
            ],
          • "additional_info": "string",
          • "email_address": "string",
          • "language": "string"
          },
        • "shipping_info": {
          • "business_name": "string",
          • "name": {
            • "prefix": "string",
            • "given_name": "string",
            • "surname": "string",
            • "middle_name": "string",
            • "suffix": "string",
            • "alternate_full_name": "string",
            • "full_name": "string"
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "address_line_3": "string",
            • "admin_area_4": "string",
            • "admin_area_3": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st",
            • "address_details": {
              • "street_number": "string",
              • "street_name": "string",
              • "street_type": "string",
              • "delivery_service": "string",
              • "building_name": "string",
              • "sub_building": "string"
              }
            }
          }
        }
      ],
    • "additional_recipients": [
      • "string"
      ],
    • "items": [
      • {
        • "id": "string",
        • "name": "string",
        • "description": "string",
        • "quantity": "string",
        • "unit_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "tax_note": "string",
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "item_date": "string",
        • "discount": {
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "unit_of_measure": "QUANTITY"
        }
      ],
    • "detail": {
      • "reference": "string",
      • "note": "string",
      • "terms_and_conditions": "string",
      • "memo": "string",
      • "attachments": [
        • {
          • "id": "string",
          • "reference_url": "http://example.com",
          • "content_type": "string",
          • "size": "string",
          • "create_time": "string"
          }
        ],
      • "currency_code": "string",
      • "payment_term": {
        • "term_type": "DUE_ON_RECEIPT"
        },
      • "metadata": {
        • "created_by": "string",
        • "last_updated_by": "string",
        • "create_time": "string",
        • "last_update_time": "string"
        }
      },
    • "invoicer": {
      • "business_name": "string",
      • "name": {
        • "prefix": "string",
        • "given_name": "string",
        • "surname": "string",
        • "middle_name": "string",
        • "suffix": "string",
        • "alternate_full_name": "string",
        • "full_name": "string"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "address_line_3": "string",
        • "admin_area_4": "string",
        • "admin_area_3": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st",
        • "address_details": {
          • "street_number": "string",
          • "street_name": "string",
          • "street_type": "string",
          • "delivery_service": "string",
          • "building_name": "string",
          • "sub_building": "string"
          }
        },
      • "phones": [
        • {
          • "country_code": "str",
          • "national_number": "string",
          • "extension_number": "string",
          • "phone_type": "FAX"
          }
        ],
      • "website": "http://example.com",
      • "tax_id": "string",
      • "additional_notes": "string",
      • "logo_url": "http://example.com",
      • "email_address": "string"
      },
    • "configuration": {
      • "tax_calculated_after_discount": true,
      • "tax_inclusive": false,
      • "allow_tip": false,
      • "partial_payment": {
        • "allow_partial_payment": false,
        • "minimum_amount_due": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      },
    • "amount": {
      • "currency_code": "str",
      • "value": "string",
      • "breakdown": {
        • "item_total": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "discount": {
          • "invoice_discount": {
            • "percent": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            },
          • "item_discount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "tax_total": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "shipping": {
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "tax": {
            • "name": "string",
            • "tax_note": "string",
            • "percent": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          },
        • "custom": {
          • "label": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        }
      },
    • "due_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "settings": {
    • "template_item_settings": [
      • {
        • "field_name": "ITEMS_QUANTITY",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "template_subtotal_settings": [
      • {
        • "field_name": "DISCOUNT",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "unit_of_measure": "QUANTITY"
}
template_configuration
The template configuration details. Includes tax information, tip, and partial payment.


tax_calculated_after_discount
boolean
 Default:  true
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
 Default:  false
Indicates whether the unit price includes tax.


 
allow_tip
boolean
 Default:  false
Indicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.
Note: This feature is not available for users in Hong Kong, Taiwan, India, or Japan.


 
object (partial_payment) 
The partial payment details. Includes the minimum amount that the invoicer expects from the payer.


 
{
  • "tax_calculated_after_discount": true,
  • "tax_inclusive": false,
  • "allow_tip": false,
  • "partial_payment": {
    • "allow_partial_payment": false,
    • "minimum_amount_due": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}
template_detail
The template-related details. Includes notes, terms and conditions, memo, and attachments.


reference
string  <= 120 characters 
The reference data. Includes a Purchase Order (PO) number.


 
note
string  <= 4000 characters 
A note to the invoice recipient. Also appears on the invoice notification email.


 
terms_and_conditions
string  <= 4000 characters 
The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.


 
memo
string  <= 500 characters 
A private bookkeeping memo for the user.


 
Array of objects (File Reference)   <= 5 
An array of PayPal IDs for the files that are attached to an invoice.


 
currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
object (payment_term) 
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.


 
object (template_metadata) 
The audit metadata. Captures all template actions on create and update.


 
{
  • "reference": "string",
  • "note": "string",
  • "terms_and_conditions": "string",
  • "memo": "string",
  • "attachments": [
    • {
      • "id": "string",
      • "reference_url": "http://example.com",
      • "content_type": "string",
      • "size": "string",
      • "create_time": "string"
      }
    ],
  • "currency_code": "string",
  • "payment_term": {
    • "term_type": "DUE_ON_RECEIPT"
    },
  • "metadata": {
    • "created_by": "string",
    • "last_updated_by": "string",
    • "create_time": "string",
    • "last_update_time": "string"
    }
}
template_display_preference
The template display preference.


hidden
boolean
 Default:  false
Indicates whether to show or hide this field.


 
{
  • "hidden": false
}
template_info
The template details. Includes invoicer business information, invoice recipients, items, and configuration.


Array of objects (recipient_info)   <= 100 items 
The billing and shipping information. Includes name, email, address, phone, and language.


 
additional_recipients
Array of strings <ppaas_common_email_address_v2>  (email_address)   <= 100 items 
An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the additional_recipients value associated with the invoice.


 
Array of objects (item)   <= 100 items 
An array of invoice line-item information.


 
object (template_detail) 
The template-related details. Includes notes, terms and conditions, memo, and attachments.


 
object (invoicer_info) 
The invoicer business information that appears on the invoice.


 
object (template_configuration) 
The template configuration details. Includes tax information, tip, and partial payment.


 
object (amount_summary_detail) 
The invoice amount summary of item total, discount, tax total, and shipping.


 
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          },
        • "phones": [
          • {
            • "country_code": "str",
            • "national_number": "string",
            • "extension_number": "string",
            • "phone_type": "FAX"
            }
          ],
        • "additional_info": "string",
        • "email_address": "string",
        • "language": "string"
        },
      • "shipping_info": {
        • "business_name": "string",
        • "name": {
          • "prefix": "string",
          • "given_name": "string",
          • "surname": "string",
          • "middle_name": "string",
          • "suffix": "string",
          • "alternate_full_name": "string",
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "address_line_3": "string",
          • "admin_area_4": "string",
          • "admin_area_3": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st",
          • "address_details": {
            • "street_number": "string",
            • "street_name": "string",
            • "street_type": "string",
            • "delivery_service": "string",
            • "building_name": "string",
            • "sub_building": "string"
            }
          }
        }
      }
    ],
  • "additional_recipients": [
    • "string"
    ],
  • "items": [
    • {
      • "id": "string",
      • "name": "string",
      • "description": "string",
      • "quantity": "string",
      • "unit_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax": {
        • "name": "string",
        • "tax_note": "string",
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "item_date": "string",
      • "discount": {
        • "percent": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "detail": {
    • "reference": "string",
    • "note": "string",
    • "terms_and_conditions": "string",
    • "memo": "string",
    • "attachments": [
      • {
        • "id": "string",
        • "reference_url": "http://example.com",
        • "content_type": "string",
        • "size": "string",
        • "create_time": "string"
        }
      ],
    • "currency_code": "string",
    • "payment_term": {
      • "term_type": "DUE_ON_RECEIPT"
      },
    • "metadata": {
      • "created_by": "string",
      • "last_updated_by": "string",
      • "create_time": "string",
      • "last_update_time": "string"
      }
    },
  • "invoicer": {
    • "business_name": "string",
    • "name": {
      • "prefix": "string",
      • "given_name": "string",
      • "surname": "string",
      • "middle_name": "string",
      • "suffix": "string",
      • "alternate_full_name": "string",
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      },
    • "phones": [
      • {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string",
        • "phone_type": "FAX"
        }
      ],
    • "website": "http://example.com",
    • "tax_id": "string",
    • "additional_notes": "string",
    • "logo_url": "http://example.com",
    • "email_address": "string"
    },
  • "configuration": {
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "allow_tip": false,
    • "partial_payment": {
      • "allow_partial_payment": false,
      • "minimum_amount_due": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "invoice_discount": {
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          },
        • "item_discount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax": {
          • "name": "string",
          • "tax_note": "string",
          • "percent": "string",
          • "amount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        },
      • "custom": {
        • "label": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      }
    },
  • "due_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
template_item_field
The field names for the invoice line items in the template.


string (template_item_field) 
The field names for the invoice line items in the template.


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


ITEMS_DESCRIPTION
The description of the item in the invoice template.


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


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


ITEMS_TAX
The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from 0 to 100. Supports up to five decimal places.


 
"ITEMS_QUANTITY"
template_item_setting
The template item setting. Sets a template as the default template or edit template.


field_name
string (template_item_field) 
The field name in template_data for which to map corresponding display preferences.


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


ITEMS_DESCRIPTION
The description of the item in the invoice template.


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


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


ITEMS_TAX
The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from 0 to 100. Supports up to five decimal places.


 
object (template_display_preference) 
The display preference.


 
{
  • "field_name": "ITEMS_QUANTITY",
  • "display_preference": {
    • "hidden": false
    }
}
template_metadata
The audit metadata. Captures all template actions on create and update.


created_by
string
The email address of the account that created the resource.


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


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
last_update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
{
  • "created_by": "string",
  • "last_updated_by": "string",
  • "create_time": "string",
  • "last_update_time": "string"
}
template_settings
The template settings. Sets a template as the default template or edit template.


Array of objects (template_item_setting) 
The template item headers display preference.


 
Array of objects (template_subtotal_setting) 
The template subtotal headers display preference.


 
{
  • "template_item_settings": [
    • {
      • "field_name": "ITEMS_QUANTITY",
      • "display_preference": {
        • "hidden": false
        }
      }
    ],
  • "template_subtotal_settings": [
    • {
      • "field_name": "DISCOUNT",
      • "display_preference": {
        • "hidden": false
        }
      }
    ]
}
template_subtotal_field
The field names in the template for discount, shipping, and custom amounts.


string (template_subtotal_field) 
The field names in the template for discount, shipping, and custom amounts.


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


SHIPPING
The shipping fee for all items in the invoice template. Also includes the tax on shipping.


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


 
"DISCOUNT"
template_subtotal_setting
The template subtotal setting. Includes the field name and display preference.


field_name
string (template_subtotal_field) 
The field name in template_data for which to map corresponding display preferences.


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


SHIPPING
The shipping fee for all items in the invoice template. Also includes the tax on shipping.


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


 
object (template_display_preference) 
The display preference.


 
{
  • "field_name": "DISCOUNT",
  • "display_preference": {
    • "hidden": false
    }
}
templates
An array of merchant-created templates with associated details that include the emails, addresses, and phone numbers from the user's PayPal profile.


Array of objects (Portable Postal Address (Medium-Grained)) 
An array of addresses in the user's PayPal profile.


 
Array of objects (phone_detail) 
An array of phone numbers in the user's PayPal profile.


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


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
emails
string <ppaas_common_email_address_v2>  (email_address)   [ 3 .. 254 ] characters ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za...
An array of emails in the user's PayPal profile.


 
{
  • "addresses": [
    • {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "address_line_3": "string",
      • "admin_area_4": "string",
      • "admin_area_3": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st",
      • "address_details": {
        • "street_number": "string",
        • "street_name": "string",
        • "street_type": "string",
        • "delivery_service": "string",
        • "building_name": "string",
        • "sub_building": "string"
        }
      }
    ],
  • "phones": [
    • {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string",
      • "phone_type": "FAX"
      }
    ],
  • "templates": [
    • {
      • "id": "string",
      • "name": "string",
      • "default_template": true,
      • "standard_template": true,
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "template_info": {
        • "primary_recipients": [
          • {
            • "billing_info": {
              • "business_name": "string",
              • "name": {
                • "prefix": null,
                • "given_name": null,
                • "surname": null,
                • "middle_name": null,
                • "suffix": null,
                • "alternate_full_name": null,
                • "full_name": null
                },
              • "address": {
                • "address_line_1": null,
                • "address_line_2": null,
                • "address_line_3": null,
                • "admin_area_4": null,
                • "admin_area_3": null,
                • "admin_area_2": null,
                • "admin_area_1": null,
                • "postal_code": null,
                • "country_code": null,
                • "address_details": { }
                },
              • "phones": [
                • null
                ],
              • "additional_info": "string",
              • "email_address": "string",
              • "language": "string"
              },
            • "shipping_info": {
              • "business_name": "string",
              • "name": {
                • "prefix": null,
                • "given_name": null,
                • "surname": null,
                • "middle_name": null,
                • "suffix": null,
                • "alternate_full_name": null,
                • "full_name": null
                },
              • "address": {
                • "address_line_1": null,
                • "address_line_2": null,
                • "address_line_3": null,
                • "admin_area_4": null,
                • "admin_area_3": null,
                • "admin_area_2": null,
                • "admin_area_1": null,
                • "postal_code": null,
                • "country_code": null,
                • "address_details": { }
                }
              }
            }
          ],
        • "additional_recipients": [
          • "string"
          ],
        • "items": [
          • {
            • "id": "string",
            • "name": "string",
            • "description": "string",
            • "quantity": "string",
            • "unit_amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "tax": {
              • "name": "string",
              • "tax_note": "string",
              • "percent": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              },
            • "item_date": "string",
            • "discount": {
              • "percent": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              },
            • "unit_of_measure": "QUANTITY"
            }
          ],
        • "detail": {
          • "reference": "string",
          • "note": "string",
          • "terms_and_conditions": "string",
          • "memo": "string",
          • "attachments": [
            • {
              • "id": "string",
              • "reference_url": "http://example.com",
              • "content_type": "string",
              • "size": "string",
              • "create_time": "string"
              }
            ],
          • "currency_code": "string",
          • "payment_term": {
            • "term_type": "DUE_ON_RECEIPT"
            },
          • "metadata": {
            • "created_by": "string",
            • "last_updated_by": "string",
            • "create_time": "string",
            • "last_update_time": "string"
            }
          },
        • "invoicer": {
          • "business_name": "string",
          • "name": {
            • "prefix": "string",
            • "given_name": "string",
            • "surname": "string",
            • "middle_name": "string",
            • "suffix": "string",
            • "alternate_full_name": "string",
            • "full_name": "string"
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "address_line_3": "string",
            • "admin_area_4": "string",
            • "admin_area_3": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st",
            • "address_details": {
              • "street_number": "string",
              • "street_name": "string",
              • "street_type": "string",
              • "delivery_service": "string",
              • "building_name": "string",
              • "sub_building": "string"
              }
            },
          • "phones": [
            • {
              • "country_code": "str",
              • "national_number": "string",
              • "extension_number": "string",
              • "phone_type": "FAX"
              }
            ],
          • "website": "http://example.com",
          • "tax_id": "string",
          • "additional_notes": "string",
          • "logo_url": "http://example.com",
          • "email_address": "string"
          },
        • "configuration": {
          • "tax_calculated_after_discount": true,
          • "tax_inclusive": false,
          • "allow_tip": false,
          • "partial_payment": {
            • "allow_partial_payment": false,
            • "minimum_amount_due": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          },
        • "amount": {
          • "currency_code": "str",
          • "value": "string",
          • "breakdown": {
            • "item_total": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "discount": {
              • "invoice_discount": {
                • "percent": null,
                • "amount": null
                },
              • "item_discount": {
                • "currency_code": null,
                • "value": null
                }
              },
            • "tax_total": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "shipping": {
              • "amount": {
                • "currency_code": null,
                • "value": null
                },
              • "tax": {
                • "name": null,
                • "tax_note": null,
                • "percent": null,
                • "amount": null
                }
              },
            • "custom": {
              • "label": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            }
          },
        • "due_amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "settings": {
        • "template_item_settings": [
          • {
            • "field_name": "ITEMS_QUANTITY",
            • "display_preference": {
              • "hidden": false
              }
            }
          ],
        • "template_subtotal_settings": [
          • {
            • "field_name": "DISCOUNT",
            • "display_preference": {
              • "hidden": false
              }
            }
          ]
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "emails": "string"
}
type
Type of the stored discount. Used to determine wheather its percentage or absolute currency value.


string (type)   [ 1 .. 20 ] characters ^[A-Z0-9_]*$
Type of the stored discount. Used to determine wheather its percentage or absolute currency value.


 Enum Value Description
PERCENT
Percentage of discount used in invoice item or in an invoice.


AMOUNT
An absolute value of discount used in invoice item or in an invoice based on the currency in invoice.


 
"PERCENT"
unit_of_measure
The unit of measure for the invoiced item.


string (unit_of_measure) 
The unit of measure for the invoiced item.


 Enum Value Description
QUANTITY
The unit of measure is quantity. This invoice template is typically used for physical goods.


HOURS
The unit of measure is hours. This invoice template is typically used for services.


AMOUNT
The unit of measure is amount. This invoice template is typically used when only amount is required.


 
"QUANTITY"