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.

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: application/json

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
application/json
{
  • "detail": {
    • "currency_code": "USD",
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "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.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices?total_required=true \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
{}

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: application/json

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
application/json
{
  • "send_to_invoicer": true
}

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
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 
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/generate-next-invoice-number \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
application/json
{
  • "invoice_number": "ee0044"
}

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 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates/@default \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
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

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: 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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

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: application/json

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

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
{
  • "detail": {
    • "currency_code": "USD",
    • "invoice_number": "#123",
    • "reference": "deal-refernce-update",
    • "invoice_date": "2018-11-12",
    • "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"
      }
    },
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/refunds/EXTR-2LG703375E477444T \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

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.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/templates \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
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: application/json
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: 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
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"
          },
        • "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": []
}

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: application/json

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
application/json
{
  • "send_to_invoicer": true,
  • "send_to_recipient": true,
  • "additional_recipients": [
    • "user@example.com"
    ]
}

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: application/json

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: 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
application/json
{
  • "method": "BANK_TRANSFER",
  • "payment_date": "2018-05-01",
  • "amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    }
}
Response samples
{
  • "payment_id": "EXTR-86F38350LX4353815"
}

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: application/json

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
application/json
{
  • "send_to_invoicer": true,
  • "additional_recipients": [
    • "customer-a@example.com",
    • "customer@example.com"
    ]
}

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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments/EXTR-86F38350LX4353815 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

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: application/json

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
application/json
{
  • "width": 400,
  • "height": 400
}
Response samples
application/json
"--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--"

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: application/json

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: 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
application/json
{
  • "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
{}

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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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"