View as Markdown
API Spec (JSON)
API Spec (YAML)
Compact modeHides field descriptions and other prose for a more compact, scannable view of the API reference.Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.
Client CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheaderScopes
https://uri.paypal.com/services/invoicing/invoices/readwriteapplication/json
TypeScript Definitions
Use the request body type in TypeScript.
namestring<currency_code>OptionalNote: The template name must be unique.
descriptionstring<currency_code>Optionaltemplate_infoobject<template_info>Optionaldetailobject<template_detail>Optionalreferencestring<currency_code>Optionalcurrency_codestring<currency_code>Requirednotestring<currency_code>Optionalterms_and_conditionsstring<currency_code>Optionalmemostring<currency_code>Optionalattachmentsobject<file_reference>[]Optionalcreate_timestring<date_time>OptionalNote: The regular expression provides guidance but does not reject all invalid dates.
tip_presetsobject<tip_preset>[]Optionalorder_detailsstring<currency_code>Optionalproject_detailsstring<currency_code>Optionalservice_detailsstring<currency_code>Optionalpayment_termsstring<currency_code>Optionalreturn_policystring<currency_code>Optionalcancellation_policystring<currency_code>Optionalservice_agreementstring<currency_code>Optionalpayment_termobject<payment_term>Optionalterm_typeenum<payment_term_type>Optionalconditional_rulesobject<payment_term_conditional_rules>Optionalearly_payment_discountobject<early_payment_discount>Optionaldiscount_end_datestring<date_no_time>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredauto_cancellationobject<auto_cancellation>Optionalcancel_by_datestring<date_no_time>Optionalmetadataobject<template_metadata>OptionalNo fields are defined.
invoicerobject<invoicer_info>Optionalorthographyenum<orthography>Optionalnameobject<person_name>Optionalorthographyenum<orthography>Optionaladdressobject<address_portable>Optionaladmin_area_4stringOptionaladmin_area_3stringOptionaladmin_area_1stringOptionalcountry_codestring<country_code>RequiredNote: The country code for Great Britain isGBand notUKas 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.
address_detailsobject<Address Details>Optionalemail_addressstring<restrictive_email_address>OptionalNote: 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.
phonesobject<phone_detail>[]Optionalcountry_codestringRequirednational_numberstringRequiredadditional_notesstring<currency_code>Optionalprimary_recipientsobject<recipient_info>[]Optionalbilling_infoobject<billing_info>Optionalorthographyenum<orthography>Optionalnameobject<person_name>Optionalorthographyenum<orthography>Optionaladdressobject<address_portable>Optionaladmin_area_4stringOptionaladmin_area_3stringOptionaladmin_area_1stringOptionalcountry_codestring<country_code>RequiredNote: The country code for Great Britain isGBand notUKas 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.
address_detailsobject<Address Details>Optionalemail_addressstring<restrictive_email_address>OptionalNote: 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.
phonesobject<phone_detail>[]Optionalcountry_codestringRequirednational_numberstringRequiredadditional_infostring<currency_code>Optionallanguagestring<language>Optionalshipping_infoobject<contact_name_address>Optionalorthographyenum<orthography>Optionalnameobject<person_name>Optionalorthographyenum<orthography>Optionaladdressobject<address_portable>Optionaladmin_area_4stringOptionaladmin_area_3stringOptionaladmin_area_1stringOptionalcountry_codestring<country_code>RequiredNote: The country code for Great Britain isGBand notUKas 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.
address_detailsobject<Address Details>Optionaladditional_recipientsarray<email_address>OptionalNote: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
namestring<currency_code>Requireddescriptionstring<currency_code>Optionalunit_amountobject<money>Requiredcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredtaxobject<tax>Optionalpercentstring<percentage>Requireditem_datestring<date_no_time>Optionaldiscountobject<discount>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredunit_of_measureenum<unit_of_measure>Optionalconfigurationobject<template_configuration>Optionalallow_tipbooleanOptionalNote: This feature is not available for users in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
partial_paymentobject<partial_payment>Optionalminimum_amount_dueobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requireddiscount_mode_preferenceenum<discount_mode_preference>Optionalthemeobject<configurable_theme>Optionalamountobject<amount_summary_detail>Optionalcurrency_codestring<currency_code>Optionalvaluestring<percentage>Optionalbreakdownobject<amount_with_breakdown>Optionalitem_totalobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requireddiscountobject<aggregated_discount>Optionalinvoice_discountobject<discount>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requireditem_discountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredtax_totalobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredshippingobject<shipping_cost>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredtaxobject<tax>Optionalpercentstring<percentage>Requiredcustomobject<custom_amount>Optionallabelstring<currency_code>Requiredamountobject<money>Optionalcurrency_codestring<currency_code>Requiredvaluestring<percentage>Requiredsettingsobject<template_settings>Optionaltemplate_item_settingsobject<template_item_setting>[]Optionalfield_nameenum<template_item_field>Optionaldisplay_preferenceobject<template_display_preference>Optionaltemplate_subtotal_settingsobject<template_subtotal_setting>[]Optionalfield_nameenum<template_subtotal_field>Optionaldisplay_preferenceobject<template_display_preference>Optionaltemplate_details_settingsobject<template_details_setting>[]Optionalfield_nameenum<template_details_settings_field>Optionaldisplay_preferenceobject<template_setting_display_preference>Optionaltemplate_policy_and_agreement_settingsobject<template_policy_and_agreement_setting>[]Optionalfield_nameenum<template_policy_and_agreement_settings_field>Optionaldisplay_preferenceobject<template_setting_display_preference>Optionaltemplate_additional_settingsobject<template_additional_setting>[]Optionalfield_nameenum<template_additional_settings_field>Optionaldisplay_preferenceobject<template_setting_display_preference>Optionalunit_of_measureenum<unit_of_measure>Optionalapplication/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v2/invoicing/templates" \ -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \ -H "Content-Type: application/json" \ -d '{ "description": "Template description", "default_template": true, "template_info": { "configuration": { "tax_calculated_after_discount": true, "show_additional_item_fields": false, "tax_inclusive": false, "allow_tip": true, "partial_payment": { "allow_partial_payment": true, "minimum_amount_due": { "currency_code": "USD", "value": "20.00" } } }, "detail": { "reference": "deal-ref", "note": "Thank you for your business.", "currency_code": "USD", "terms_and_conditions": "No refunds after 30 days.", "memo": "This is a long contract", "attachments": [ { "id": "Screen Shot 2018-11-23 at 16.45.01.png", "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE" } ], "payment_term": { "term_type": "NET_10" }, "service_agreement": "This agreement covers the terms of the provided consulting services.", "tip_presets": [ { "percent": "10" }, { "percent": "15" }, { "percent": "20" } ] }, "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": "[email protected]", "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": "[email protected]", "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": [ "[email protected]" ], "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 } } ], "template_invoice_details_settings": [ { "field_name": "ORDER_DETAILS", "display_preference": { "hidden": false } }, { "field_name": "PROJECT_DETAILS", "display_preference": { "hidden": true } }, { "field_name": "SERVICE_DETAILS", "display_preference": { "hidden": true } } ], "template_policy_and_agreement_settings": [ { "field_name": "CANCELLATION_POLICY", "display_preference": { "hidden": true } }, { "field_name": "PAYMENT_TERMS", "display_preference": { "hidden": true } }, { "field_name": "RETURN_POLICY", "display_preference": { "hidden": true } }, { "field_name": "SERVICE_AGREEMENT", "display_preference": { "hidden": true } }, { "field_name": "TERMS_AND_CONDITIONS", "display_preference": { "hidden": false } } ], "template_additional_settings": [ { "field_name": "REFERENCE", "display_preference": { "hidden": false } }, { "field_name": "ATTACHMENT", "display_preference": { "hidden": false } }, { "field_name": "MEMO", "display_preference": { "hidden": false } } ] }, "unit_of_measure": "QUANTITY", "standard_template": false }'{ "id": "TEMP-19V05281TU309413B", "name": "reference-temp", "description": "Template description", "default_template": true, "template_info": { "configuration": { "tax_calculated_after_discount": true, "show_additional_item_fields": false, "tax_inclusive": false, "allow_tip": true, "partial_payment": { "allow_partial_payment": true, "minimum_amount_due": { "currency_code": "USD", "value": "20.00" } } }, "detail": { "reference": "deal-ref", "note": "Thank you for your business.", "currency_code": "USD", "terms_and_conditions": "No refunds after 30 days.", "memo": "This is a long contract", "attachments": [ { "id": "Screen Shot 2018-11-23 at 16.45.01.png", "reference_url": "https://api-m.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE" } ], "payment_term": { "term_type": "NET_10" }, "tip_presets": [ { "percent": "10" }, { "percent": "15" }, { "percent": "20" } ], "metadata": { "create_time": "2018-12-03T03:38:46z" } }, "invoicer": { "name": { "given_name": "David", "surname": "Larusso" }, "address": { "address_line_1": "1234 First Street", "address_line_2": "337673 Hillside Court", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "98765", "country_code": "US" }, "email_address": "[email protected]", "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": "[email protected]", "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": [ "[email protected]" ], "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 } } ], "template_invoice_details_settings": [ { "field_name": "ORDER_DETAILS", "display_preference": { "hidden": false } }, { "field_name": "PROJECT_DETAILS", "display_preference": { "hidden": true } }, { "field_name": "SERVICE_DETAILS", "display_preference": { "hidden": true } } ], "template_policy_and_agreement_settings": [ { "field_name": "CANCELLATION_POLICY", "display_preference": { "hidden": true } }, { "field_name": "PAYMENT_TERMS", "display_preference": { "hidden": true } }, { "field_name": "RETURN_POLICY", "display_preference": { "hidden": true } }, { "field_name": "SERVICE_AGREEMENT", "display_preference": { "hidden": true } }, { "field_name": "TERMS_AND_CONDITIONS", "display_preference": { "hidden": false } } ], "template_additional_settings": [ { "field_name": "REFERENCE", "display_preference": { "hidden": false } }, { "field_name": "ATTACHMENT", "display_preference": { "hidden": false } }, { "field_name": "MEMO", "display_preference": { "hidden": false } } ] }, "unit_of_measure": "QUANTITY", "standard_template": false, "links": [ { "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B", "rel": "delete", "method": "DELETE" }, { "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B", "rel": "replace", "method": "PUT" } ]}