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.Client CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheaderScopes
https://uri.paypal.com/services/invoicing/invoices/readwritehttps://uri.paypal.com/services/invoicing/internalapplication/json
TypeScript Definitions
Use the request body type in TypeScript.
plan_detailobject<plan>Requiredfrequencyobject<plan_frequency>Requiredstart_series_datestring<date_no_time>Optionalrecurring_infoobject<recurring_info>Requireddetailobject<recurring_series_detail>Requiredcurrency_codestring<currency_code>Requiredattachmentsobject<file_reference>[]Optionalcreate_timestring<date_time>OptionalNote: The regular expression provides guidance but does not reject all invalid dates.
payment_termobject<recurring_payment_term>Optionalterm_typeenum<payment_term_type>Optionalconditional_rulesobject<recurring_payment_term_conditional_rules>Optionalearly_payment_discountobject<recurring_early_payment_discount>Optionalconditionenum<conditional_rule_relative_conditions>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredauto_cancellationobject<recurring_auto_cancellation>Optionalconditionenum<conditional_rule_relative_conditions>Optionaltip_presetsobject<tip_preset>[]Optionalpercentstring<percentage>Optionalinvoicerobject<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_numberstringRequiredprimary_recipientsobject<recipient_info>[]Requiredbilling_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_numberstringRequiredlanguagestring<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>Optionalitemsobject<item>[]Optionalunit_amountobject<money>Requiredcurrency_codestring<currency_code>RequiredvaluestringRequiredtaxobject<tax>Optionalpercentstring<percentage>Requireditem_datestring<date_no_time>Optionaldiscountobject<discount>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredunit_of_measureenum<unit_of_measure>Optionalconfigurationobject<recurring_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>RequiredvaluestringRequiredtemplate_idstringOptionalYou can either use an existing template ID or create a new template via the create template API and then use the newly created template's ID.
payment_method_overridesobject<override_payment_method_detail>[]OptionalNote: Payment method availability depends on the merchant's country, the buyer's country, and the invoice amount. Override configurations only take effect if the specified payment method is available for the invoice.
payment_method_typeenum<override_payment_method_type>OptionalNote: To usePAY_BY_BANK, you must first complete the onboarding process. Visit the onboarding page to get started. Once onboarding is complete, you can configurePAY_BY_BANKas a payment method.
rulesobject<override_payment_method_rule>[]Optionalrule_typeenum<override_payment_method_rule_type>RequiredSystem-defined threshold limits by payment method:
- PAY_BY_BANK - $1000
themeobject<configurable_theme>Optionalamountobject<amount_summary_detail>Optionalcurrency_codestring<currency_code>OptionalvaluestringOptionalbreakdownobject<amount_with_breakdown>Optionalitem_totalobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequireddiscountobject<aggregated_discount>Optionalinvoice_discountobject<discount>Optionalpercentstring<percentage>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequireditem_discountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredtax_totalobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredshippingobject<shipping_cost>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredtaxobject<tax>Optionalpercentstring<percentage>Requiredcustomobject<custom_amount>Optionalamountobject<money>Optionalcurrency_codestring<currency_code>RequiredvaluestringRequiredapplication/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v2/invoicing/recurring-invoices/RI-5VG36420NF0175035" \ -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \ -H "Content-Type: application/json" \ -d '{ "plan_detail": { "total_cycles": 8, "frequency": { "interval_unit": "MONTH", "interval_count": 2 }, "start_series_date": "2026-01-19" }, "recurring_info": { "detail": { "reference": "0002", "currency_code": "USD", "note": "Thank you", "terms_and_conditions": "Your terms and conditions", "memo": "Gift pack", "category_code": "SHIPPABLE", "payment_term": { "term_type": "DUE_ON_RECEIPT" } }, "primary_recipients": [ { "billing_info": { "email_address": "[email protected]" } } ], "items": [ { "name": "pen", "quantity": "2", "unit_amount": { "currency_code": "USD", "value": "12.00" }, "unit_of_measure": "QUANTITY" } ], "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": "2.00" } } } } }'{ "id": "RI-9Y6699772R098892C", "status": "ACTIVE", "plan_detail": { "total_cycles": 8, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "start_series_date": "2026-01-19", "completed_cycles": 0 }, "recurring_info": { "detail": { "reference": "0001", "currency_code": "USD", "note": "Thank you", "terms_and_conditions": "Your terms and conditions", "memo": "Gift pack", "category_code": "SHIPPABLE", "payment_term": { "term_type": "DUE_ON_RECEIPT" } }, "primary_recipients": [ { "billing_info": { "email_address": "[email protected]" } } ], "items": [ { "id": "ITEM-3LD558161T864042C", "name": "pen", "quantity": "1", "unit_amount": { "currency_code": "USD", "value": "12.00" }, "unit_of_measure": "QUANTITY" } ], "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": "2.00" } }, "template_id": "TEMP-1B23377148371954V" }, "amount": { "breakdown": { "item_total": { "currency_code": "USD", "value": "12.00" }, "discount": { "invoice_discount": { "amount": { "currency_code": "USD", "value": "0.00" } }, "item_discount": { "currency_code": "USD", "value": "0.00" } }, "tax_total": { "currency_code": "USD", "value": "0.00" } }, "currency_code": "USD", "value": "12.00" } }, "metadata": { "create_time": "2026-01-20T05:17:06Z", "last_update_time": "2026-01-20T05:17:06Z" }, "links": [ { "href": "https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201", "rel": "delete", "method": "DELETE" }, { "href": "https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201", "rel": "replace", "method": "PUT" }, { "href": "https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201/cancel", "rel": "cancel", "method": "POST" }, { "href": "https://api-m.paypal.com/v2/invoicing/recurring-invoices/RI-8K163274UC7208201/activate", "rel": "activate", "method": "POST" } ]}