On this page
No Headings
An array of merchant recurring invoices series. It includes HATEOAS links for navigation.
objectrecurring_invoicesarrayThe list of recurring invoices series that match the search criteria.
itemsobjectA recurring invoice series that automatically generates and sends invoices to customers on a scheduled basis. Contains all configuration, status, and metadata for the series.
idstring^(RI-)[A-Z0-9]+$The unique identifier for the recurring invoice series. This ID is used to reference and manage the series in all API operations.
statusstring"DRAFT", "ACTIVE", "CANCELLED", "EXPIRED"The lifecycle status of a recurring invoice series. Determines the operational state and whether invoices are actively being generated.
plan_detailrequiredobjectThe scheduling and recurrence configuration that defines when and how often invoices are automatically generated and sent to customers in a recurring series.
total_cyclesintegerThe total number of billing cycles (invoices) that will be generated in this recurring series. Once all cycles are completed, the series automatically expires. Note: if not set, then the series will be indefinite.
frequencyrequiredobjectThe frequency of the recurring invoice series cycle.
The billing frequency that determines the time interval between successive invoice generations. Defines how often invoices are sent to the customer (e.g., weekly, monthly, yearly).
interval_unitrequiredstring"DAY", "WEEK", "MONTH", "YEAR"The time unit for the recurring invoice cycle interval. Used together with interval_count to determine the frequency of invoice generation.
interval_countrequiredinteger1The number of intervals between each recurring invoice cycle. For example, an interval_count of 2 with interval_unit of MONTH means the invoice recurs every 2 months.
start_series_dateobject^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$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.
The date when the recurring series begins and the first invoice is generated. Must be specified in yyyy-MM-DD format and cannot be a past date. The start date must be either today or a future date. Note: If it is not explicitly passed then the system will assume current date as start series date.
next_occurrence_dateobject^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$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.
The calculated date when the next invoice in the series will be automatically generated and sent. This date is determined based on the frequency and the last invoice sent date.
completed_cyclesintegerThe number of billing cycles (invoices) that have already been generated and sent in this recurring series. This counter increments with each invoice sent and helps track progress toward the total cycles.
recurring_inforequiredobjectComprehensive information about a recurring invoice series, including invoice details, participant information, line items, and amount calculations.
detailrequiredobjectThe detailed information for a recurring invoice series, including payment terms and other configuration settings.
The recurring series configuration details, including payment terms and scheduling information.
invoicerobjectThe invoicer business information that appears on the invoice.
The merchant or business information for the party issuing the recurring invoices. Includes business name, contact details (email, address, phone, fax), tax identification number, additional notes, and logo URL.
primary_recipientsrequiredarrayThe primary recipient of the recurring invoices. Contains billing and shipping information including the recipient's name, email address, physical address, phone number, and preferred language.
itemsobjectThe billing and shipping information. Includes name, email, address, phone, and language.
billing_infoobjectThe billing information of the invoice recipient. Includes name, address, email, phone, and language.
email_addressobject^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(?!\.)){1,64}(?<!\.)@(?:[A-Za-z0-9-]|\.(?!\.))+\.[a-zA-Z]{2,}$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.
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.
The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
phonesarrayThe invoice recipient's phone numbers. Extension number is not supported.
itemsobjectThe phone details. Includes the phone number and type.
additional_infostring^[\S\s]*$Any additional information about the recipient.
languageobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$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.
The language in which to show the invoice recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.
shipping_infoobjectThe contact information of the user. Includes name and address.
The recipient's shipping information. Includes the user's contact information, which includes name and address.
additional_recipientsarrayAdditional email addresses to receive carbon copy (CC) notifications when invoices in this series are sent.
itemsobject^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$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.
itemsarrayThe line items that will appear on each invoice in the recurring series. Each item includes product or service details, quantity, unit price, and any applicable discounts or taxes.
itemsobjectAn array of invoice line item information. The maximum items for an invoice is 100.
idstring^[\S\s]*$The ID of the invoice line item.
namerequiredstring^[\S\s]*$The item name for the invoice line item.
descriptionstring^[\S\s]*$The item description for the invoice line item.
quantityrequiredstring^\d+(.\d{1,5})?$The quantity of the item that the invoicer provides to the payer. Value is from -1000000 to 1000000. Supports up to five decimal places.
unit_amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The unit price of the item. This does not include tax and discount. Value is from -1000000 to 1000000. Supports up to two decimal places.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.taxobjectThe tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total.
The tax associated with the item. The tax amount is added to the item total. Value is from 0 to 100. Supports up to five decimal places.
namerequiredstring^[\s\S]*$The name of the tax applied on the invoice items.
percentrequiredobject^((-?[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.
The tax rate. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The calculated tax amount. The tax amount is added to the item total.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_notestring^[\s\S]*$The tax note used to track the tax related data.
item_dateobject^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$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.
The date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-ddTz.
discountobjectThe discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
percentobject^((-?[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.
The discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The invoice level discount amount. Value is from 0 to 1000000. Supports up to two decimal places.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.unit_of_measureobject"QUANTITY", "HOURS", "AMOUNT"The unit of measure for the invoiced item.
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.configurationobjectThe invoice configuration details. Includes partial payment, tip, and tax calculated after discount.
Configuration settings for invoices in this series. Defines whether partial payments are allowed, tip options, and whether tax is calculated before or after applying discounts.
amountobjectThe invoice amount summary of item total, discount, tax total, and shipping.
The calculated amount breakdown for each invoice in the series, including subtotal of all items, total discounts applied, tax amounts, and shipping costs. Note: Only invoice-level discount, shipping, and custom amounts are accepted. The rest of the fields are not mandatory and are ignored if set. They are automatically computed irrespective of the values set in the request.
currency_codestring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuestring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.breakdownobjectThe breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any.
item_totalobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The subtotal for all items. Must equal the sum of (items[].unit_amount * items[].quantity) for all items.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.discountobjectThe 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.
invoice_discountobjectThe discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
percentobject^((-?[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.
The discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The invoice level discount amount. Value is from 0 to 1000000. Supports up to two decimal places.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.item_discountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_totalobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The aggregated amount of the item and shipping taxes.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.shippingobjectThe shipping fee for all items. Includes tax on shipping.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The shipping amount. Value is from 0 to 1000000. Supports up to two decimal places.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.taxobjectThe tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total.
The tax associated with the shipping.
namerequiredstring^[\s\S]*$The name of the tax applied on the invoice items.
percentrequiredobject^((-?[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.
The tax rate. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The calculated tax amount. The tax amount is added to the item total.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_notestring^[\s\S]*$The tax note used to track the tax related data.
customobjectThe custom amount to apply to an invoice. If you include a label, you must include a custom amount.
labelrequiredstring^[\S\s]*$The label to the custom amount of the invoice.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The custom amount value. Value is from -1000000 to 1000000. Supports up to two decimal places.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.metadataobjectComprehensive audit and tracking metadata that captures key lifecycle events and actions performed on the recurring invoice series, including creation, updates and cancellation.
Audit and tracking information for the recurring series, including creation timestamp, last update timestamp and cancellation information if applicable.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstring^.*$The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstring^.*$The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"The HTTP method required to make the related call.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstring^.*$The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstring^.*$The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"The HTTP method required to make the related call.