Invoices (2)

API Version v2
?This API is currently not supported by our SDK

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

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

Array of objects (recipient_info) [ 0 .. 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) [ 0 .. 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) [ 0 .. 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 (invoice_settings)

The settings for the invoice.

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
201

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

Request samples
{
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      },
    • "order_details": "Order #12345 placed on January 15, 2023.",
    • "project_details": "Website redesign project for client XYZ Corp.",
    • "service_details": "Consulting services provided from Jan-Mar 2023.",
    • "cancellation_policy": "Services may be cancelled with 14-day notice.",
    • "payment_terms": "Payment due within 10 days of invoice date.",
    • "return_policy": "All sales are final. No returns accepted after 30 days.",
    • "service_agreement": "Services provided as per agreement dated Jan 1, 2023.",
    • "tip_presets": [
      • {
        • "percent": "15"
        },
      • {
        • "percent": "20"
        },
      • {
        • "percent": "25"
        }
      ]
    },
  • "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": "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"
          }
        }
      }
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DATE",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "ITEM_TAX",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DISCOUNT",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_additional_settings": [
      • {
        • "field_name": "ATTACHMENT",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "MEMO",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "REFERENCE",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_policy_and_agreement_settings": [
      • {
        • "field_name": "TERMS_AND_CONDITIONS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "PAYMENT_TERMS",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_details_settings": [
      • {
        • "field_name": "ORDER_DETAILS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "PROJECT_DETAILS",
        • "display_preference": {
          • "hidden": true
          }
        }
      ]
    }
}
Response samples
{
  • "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  • "status": "DRAFT",
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      },
    • "order_details": "Order #12345 placed on January 15, 2023.",
    • "project_details": "Website redesign project for client XYZ Corp.",
    • "service_details": "Consulting services provided from Jan-Mar 2023.",
    • "cancellation_policy": "Services may be cancelled with 14-day notice.",
    • "payment_terms": "Payment due within 10 days of invoice date.",
    • "return_policy": "All sales are final. No returns accepted after 30 days.",
    • "service_agreement": "Services provided as per agreement dated Jan 1, 2023.",
    • "tip_presets": [
      • {
        • "percent": "15"
        },
      • {
        • "percent": "20"
        },
      • {
        • "percent": "25"
        }
      ],
    • "metadata": {}
    },
  • "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": "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": "[email protected]",
        • "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,
    • "allow_only_pay_by_bank": 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"
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DATE",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "ITEM_TAX",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DISCOUNT",
        • "display_preference": {
          • "hidden": true
          }
        }
      ]
    },
  • "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 [ 0 .. 2147483647 ] characters ^.*$

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

Request Body schema:
any
Responses
200

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

Request samples
{ }
Response samples
{}

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice to send.

Request Body schema:

The email or SMS notification to send to the payer when they send an invoice..

subject
string [ 0 .. 4000 ] characters ^[\S\s]*$

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

Note: User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.

note
string [ 0 .. 4000 ] characters ^[\S\s]*$

A note to the payer.

Note: User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.

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) [ 0 .. 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

The server has accepted the request and will execute it at a later time.

Request samples
{
  • "send_to_invoicer": true
}
Response samples
{}

Show invoice details

get/v2/invoicing/invoices/{invoice_id}

Shows details for an invoice, by ID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string [ 0 .. 2147483647 ] characters ^.*$

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": {
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      },
    • "order_details": "Order #12345 placed on January 15, 2023.",
    • "project_details": "Website redesign project for client XYZ Corp.",
    • "service_details": "Consulting services provided from Jan-Mar 2023.",
    • "cancellation_policy": "Services may be cancelled with 14-day notice.",
    • "payment_terms": "Payment due within 10 days of invoice date.",
    • "return_policy": "All sales are final. No returns accepted after 30 days.",
    • "service_agreement": "Services provided as per agreement dated Jan 1, 2023.",
    • "tip_presets": [
      • {
        • "percent": "15"
        },
      • {
        • "percent": "20"
        },
      • {
        • "percent": "25"
        }
      ],
    • "metadata": {}
    },
  • "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": "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": "[email protected]",
        • "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,
    • "allow_only_pay_by_bank": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B",
    • "has_conditional_rule": true
    },
  • "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"
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DATE",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "ITEM_TAX",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DISCOUNT",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_additional_settings": [
      • {
        • "field_name": "ATTACHMENT",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "MEMO",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "REFERENCE",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_policy_and_agreement_settings": [
      • {
        • "field_name": "PAYMENT_TERMS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "TERMS_AND_CONDITIONS",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_details_settings": [
      • {
        • "field_name": "ORDER_DETAILS",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "PROJECT_DETAILS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "SERVICE_DETAILS",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice to update.

query Parameters
send_to_recipient
boolean
Default: true

Indicates whether to send the invoice update notification to the recipient.

send_to_invoicer
boolean
Default: true

Indicates whether to send the invoice update notification to the merchant.

Request Body schema: application/json
required

A representation of changes to make in the invoice.

Array of objects (recipient_info) [ 0 .. 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) [ 0 .. 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) [ 0 .. 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 (invoice_settings)

The settings for the invoice.

object (payments)

An array of payments registered against the invoice.

object (refunds)

The invoicing refund details. Includes the refund type, date, amount, and method.

Responses
200

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

Request samples
application/json
{
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-refernce-update",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      },
    • "order_details": "Updated order #12345 details from Jan 15, 2023.",
    • "project_details": "Updated website redesign project for XYZ Corp - added mobile optimization.",
    • "service_details": "Additional consulting services Jan-Apr 2023.",
    • "cancellation_policy": "Updated: Services may be cancelled with 30-day notice.",
    • "payment_terms": "Updated: Payment due within 15 days of invoice date.",
    • "return_policy": "Updated: All sales are final. No returns accepted after 15 days.",
    • "service_agreement": "Updated: Services provided as per revised agreement dated Feb 1, 2023.",
    • "tip_presets": [
      • {
        • "percent": "15"
        },
      • {
        • "percent": "20"
        },
      • {
        • "percent": "25"
        }
      ]
    },
  • "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": "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"
        }
      }
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DATE",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "ITEM_TAX",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DISCOUNT",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_additional_settings": [
      • {
        • "field_name": "ATTACHMENT",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "MEMO",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "REFERENCE",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_policy_and_agreement_settings": [
      • {
        • "field_name": "TERMS_AND_CONDITIONS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "PAYMENT_TERMS",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "CANCELLATION_POLICY",
        • "display_preference": {
          • "hidden": false
          }
        }
      ],
    • "invoice_details_settings": [
      • {
        • "field_name": "SERVICE_DETAILS",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    }
}
Response samples
{
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "detail": {
    • "invoice_number": "#123",
    • "reference": "deal-refernce-update",
    • "invoice_date": "2018-11-12",
    • "currency_code": "USD",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      },
    • "order_details": "Updated order #12345 details from Jan 15, 2023.",
    • "project_details": "Updated website redesign project for XYZ Corp - added mobile optimization.",
    • "service_details": "Additional consulting services Jan-Apr 2023.",
    • "cancellation_policy": "Updated: Services may be cancelled with 30-day notice.",
    • "payment_terms": "Updated: Payment due within 15 days of invoice date.",
    • "return_policy": "Updated: All sales are final. No returns accepted after 15 days.",
    • "service_agreement": "Updated: Services provided as per revised agreement dated Feb 1, 2023.",
    • "tip_presets": [
      • {
        • "percent": "15"
        },
      • {
        • "percent": "20"
        },
      • {
        • "percent": "25"
        }
      ],
    • "metadata": {}
    },
  • "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": "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": "[email protected]",
        • "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,
    • "allow_only_pay_by_bank": 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"
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DATE",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "ITEM_TAX",
        • "display_preference": {
          • "hidden": false
          }
        },
      • {
        • "field_name": "ITEM_DISCOUNT",
        • "display_preference": {
          • "hidden": false
          }
        }
      ]
    },
  • "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 [ 0 .. 2147483647 ] characters ^.*$

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'
Response samples
application/json
{ }

Search for invoices

post/v2/invoicing/search-invoices

Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.

SecurityOauth2
Request
query Parameters
page
integer [ 1 .. 1000 ]
Default: 1

The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.

page_size
integer [ 1 .. 100 ]
Default: 20

The page size for the search results.

total_required
boolean
Default: false

Indicates whether the to show total_pages and total_items in the response.

Request Body schema:

The invoice search can be used to retrieve the invoices based on the search parameters.

recipient_email
string [ 0 .. 254 ] characters ^[\S\s]*$

Filters the search by the email address.

recipient_first_name
string [ 0 .. 140 ] characters ^[\S\s]*$

Filters the search by the recipient first name.

recipient_last_name
string [ 0 .. 140 ] characters ^[\S\s]*$

Filters the search by the recipient last name.

recipient_business_name
string [ 0 .. 300 ] characters ^[\S\s]*$

Filters the search by the recipient business name.

invoice_number
string [ 0 .. 25 ] characters ^[\S\s]*$

Filters the search by the invoice number.

status
Array of strings (invoice_status) [ 0 .. 5 ] items

An array of status values.

Items Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

reference
string [ 0 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

memo
string [ 0 .. 500 ] characters ^[\S\s]*$

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 [ 0 .. 5 ] items

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

currency_code
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

object (amount_range)

The amount range.

object (date_range)

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

object (date_range)

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

object (Date and Time Range)

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

Responses
200

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

Request samples
{
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "USD",
      • "value": "50.00"
      },
    • "upper_amount": {
      • "currency_code": "USD",
      • "value": "50.00"
      }
    },
  • "invoice_date_range": {
    • "start": "2018-06-01",
    • "end": "2018-06-21"
    }
}
Response samples
{}

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice to cancel.

Request Body schema:
required

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

subject
string [ 0 .. 4000 ] characters ^[\S\s]*$

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

Note: User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.

note
string [ 0 .. 4000 ] characters ^[\S\s]*$

A note to the payer.

Note: User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.

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) [ 0 .. 100 ] items

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

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

Responses
204

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

Request samples
{
  • "send_to_invoicer": true,
  • "send_to_recipient": true,
  • "additional_recipients": []
}
Response samples
application/json
{ }

Send invoice reminder

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

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

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

SecurityOauth2
Request
path Parameters
invoice_id
required
string [ 0 .. 2147483647 ] characters ^.*$

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

Request Body schema:

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

subject
string [ 0 .. 4000 ] characters ^[\S\s]*$

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

Note: User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.

note
string [ 0 .. 4000 ] characters ^[\S\s]*$

A note to the payer.

Note: User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.

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) [ 0 .. 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
{}
Response samples
application/json
{ }

Record payment for invoice

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

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

SecurityOauth2
Request
path Parameters
invoice_id
required
string [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice to mark as paid.

Request Body schema:
required

The details of the payment to record against the invoice.

payment_id
string [ 0 .. 22 ] characters ^[\S\s]*$

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

note
string [ 0 .. 2000 ] characters ^[\S\s]*$

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.

payment_date_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.

method
required
string (payment_method) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

object (Money)

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

object (contact_information)

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

Responses
200

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

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

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice from which to delete an external payment transaction.

transaction_id
required
string [ 0 .. 2147483647 ] characters ^.*$

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'
Response samples
application/json
{ }

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice to mark as refunded.

Request Body schema:
required

The details of the refund to record against the invoice.

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

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

object (Money)

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

method
required
string (payment_method) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

Responses
200

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

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

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice from which to delete the external refund transaction.

transaction_id
required
string [ 0 .. 2147483647 ] characters ^.*$

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'
Response samples
application/json
{ }

Generate invoice number

post/v2/invoicing/generate-next-invoice-number

Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after INVOICE-1234 is INVOICE-1235.

SecurityOauth2
Request
Request Body schema:

Is the fetch type invoice number or id.

fetch_id
boolean
Default: "false"

Optional to decide the number or ID.

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
{
  • "fetch_id": true
}
Response samples
application/json
{
  • "invoice_id": "INV2-Z56S-5LLA-Q52L-CPZ5"
}

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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the invoice for which to generate a QR code.

Request Body schema:

Optional configuration parameters to adjust QR code width, height and the encoded URL.

width
integer [ 150 .. 500 ]
Default: 500

The width, in pixels, of the QR code image. Value is from 150 to 500.

height
integer [ 150 .. 500 ]
Default: 500

The height, in pixels, of the QR code image. Value is from 150 to 500.

action
string [ 0 .. 7 ] characters (?i)^(pay|details)$
Default: "pay"

The type of URL for which to generate a QR code. Valid values are pay and details.

Responses
200

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

Request samples
{
  • "width": 400,
  • "height": 400
}
Response samples
multipart/form-data
--95dbdbed-7536-4c24-b5ca-bcdbc0006612 Content-Disposition: form-data; name="image" Content-Type: application/octet-stream iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABxUlEQVR42u2WMY7kIBBFq0VA1n0BS1yDjCvZF7DxBdxXIuMaSFzAzgiQaz6t9mxLm1AbrCYYy4H1AlT1f9XHxH89lX7Z/2KJKN3CMIW6FCInYplLPtisoU6FTyHzti6RN5tPm+5ixrtTp0uP8g8s744eMS1yxvikNEOJz966GPTLaOL1fmjaxfAkaLCy2t2Hl10sPUIaNY1araFhCat3TbODDPkZ68Ii1sqfX62c1rzP62W8uWG0aiMaxSyvpS4hez2MzXkZg+FL4NNCwku/XtZ8g/Be550+Pe9jWj0x41rt1ngZyxzYa+NpmDjNMlYx1yhhs2glM8vY3IQ3qGWz9Tqvk7F3cGyYNd3KQDKGSWFGDjFNIZ8yhuWgR8gb5jR8+9bJ8rPUCd3oYbY4VcQqaWSYWRGcdnhnSS+D6lhKJIE5+JrTXtaquDtzuuypXrV0stRKwLAUzFodnYjxERP28ihtLw8WsbQE7JbxCD9SmxMxfsUYpiZ7lxYWMewltzuqKMz4n13tYi3vl6jW2FJQynBH+Za7Zie6sZRhNVXLTkqTmGUE5xSRu5dv3Qz3uYdj0bwkFLGWfxxoJMXx28tO9vu/9oPYF0bR/hBeOiwMAAAAAElFTkSuQmCC --95dbdbed-7536-4c24-b5ca-bcdbc0006612--

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 [ 0 .. 2147483647 ] characters (?i)^(all|none)$
Default: "all"

The fields to return in the response. Value is all or none. To return only the template name, ID, and default attributes, specify none.

page
integer [ 1 .. 1000 ]
Default: 1

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

page_size
integer [ 1 .. 100 ]
Default: 20

The maximum number of templates to return in the response.

Request Body schema:
any
Responses
200

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

Request samples
{ }
Response samples
{
  • "addresses": [
    • {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • {
      • "address_line_1": "26303 E 8216 N",
      • "address_line_2": "045608 Ocean Bay Plaza #02",
      • "admin_area_2": "Garden City",
      • "admin_area_1": "NY",
      • "postal_code": "11530",
      • "country_code": "US"
      }
    ],
  • "emails": "[email protected], [email protected]",
  • "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",
      • "description": "Template description",
      • "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": "[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": [],
        • "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": []
      },
    • {},
    • {}
    ]
}

Create template

post/v2/invoicing/templates

Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.

Note: Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes Quantity, Hours, and Amount.

SecurityOauth2
Request
Request Body schema:
required
name
string [ 1 .. 500 ] characters ^[\S\s]*$

The template name.

Note: The template name must be unique.

description
string [ 1 .. 160 ] characters ^[\S\s]*$

The detailed description of the template.

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) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unit of measure for the invoiced item.

Enum Value Description
QUANTITY

The unit of measure is quantity. This invoice template is typically used for physical goods.

HOURS

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

AMOUNT

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

Responses
201

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

Request samples
{
  • "description": "Template description",
  • "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": "[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": [],
    • "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
}
Response samples
{
  • "id": "TEMP-19V05281TU309413B",
  • "name": "reference-temp",
  • "description": "Template description",
  • "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": "[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": [],
    • "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": []
}

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",
  • "description": "Default Template description",
  • "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": "[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": [],
    • "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 [ 0 .. 2147483647 ] characters ^.*$

The ID of the template for which to show details.

Request Body schema: application/json
required

A representation of changes to make in the template.

name
string [ 1 .. 500 ] characters ^[\S\s]*$

The template name.

Note: The template name must be unique.

description
string [ 1 .. 160 ] characters ^[\S\s]*$

The detailed description of the template.

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) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unit of measure for the invoiced item.

Enum Value Description
QUANTITY

The unit of measure is quantity. This invoice template is typically used for physical goods.

HOURS

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

AMOUNT

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

Responses
200

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

Request samples
application/json
{
  • "description": "Template description updated",
  • "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": "[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": [],
    • "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": true
          }
        },
      • {
        • "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
}
Response samples
application/json
{
  • "id": "TEMP-19V05281TU309413B",
  • "name": "reference-temp",
  • "description": "Template description updated",
  • "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": "[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": [],
    • "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_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_item_settings": [
      • {
        • "field_name": "items.date",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "field_name": "items.discount",
        • "display_preference": {
          • "hidden": true
          }
        },
      • {
        • "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_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": []
}

Delete template

delete/v2/invoicing/templates/{template_id}

Deletes a template, by ID.

SecurityOauth2
Request
path Parameters
template_id
required
string [ 0 .. 2147483647 ] characters ^.*$

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'
Response samples
application/json
{ }

List Connections.

get/v2/invoicing/accounting-sync/merchant/connections

Lists connections to accounting platforms per merchant.

SecurityOauth2
Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/accounting-sync/merchants/connections \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
application/json
{
  • "connections": [
    • {
      • "platform_name": "QB",
      • "last_sync_time": "2025-01-09T12:30:45Z",
      • "last_sync_status": "SUCCESS"
      },
    • {
      • "platform_name": "Xero",
      • "last_sync_time": "2025-01-08T15:22:10Z",
      • "last_sync_status": "FAILED"
      }
    ]
}

List Connection Status for an Invoice.

get/v2/invoicing/accounting-sync/invoices/{id}/connections

Lists connections to accounting platforms per invoice.

SecurityOauth2
Request
path Parameters
id
required
string [ 1 .. 24 ] characters ^[0-9]+$

The invoice id of the account.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/accounting-sync/invoices/4779930204621ABC201/connections \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
application/json
{
  • "connections": [
    • {
      • "platform_name": "QBO",
      • "last_sync_timestamp": "2025-01-09T12:30:45Z",
      • "last_sync_status": "SUCCESS"
      },
    • {
      • "platform_name": "Xero",
      • "last_sync_timestamp": "2025-01-08T15:22:10Z",
      • "last_sync_status": "FAILED"
      }
    ]
}

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

aging_bucket

A single aging bucket containing invoice counts and totals for a specific time range.

from
integer [ 0 .. 1000 ]

Inclusive lower bound in days; null when not applicable (e.g., NO_DUE).

to
integer [ 0 .. 1000 ]

Inclusive upper bound in days; null if open-ended (e.g., NET_90+).

count
required
integer [ 0 .. 2147483647 ]

Number of invoices in this bucket.

label
required
string (aging_bucket_label) [ 1 .. 100 ] characters ^[A-Z0-9_+]+$

Bucket label representing the aging time range.

Enum Value Description
NO_DUE

Invoices with no due date or not yet due.

NET_30

Invoices due within 0-30 days.

NET_30_60

Invoices due within 31-60 days.

NET_60_90

Invoices due within 61-90 days.

NET_90

Invoices due more than 90 days.

required
object (Money)

Total amount for invoices in this bucket, in the row currency.

{
  • "from": 1000,
  • "to": 1000,
  • "count": 2147483647,
  • "label": "NO_DUE",
  • "total": {
    • "currency_code": "str",
    • "value": "string"
    }
}

aging_bucket_label

Aging bucket label enum representing different time ranges for invoice aging analysis.

string (aging_bucket_label) [ 1 .. 100 ] characters ^[A-Z0-9_+]+$

Aging bucket label enum representing different time ranges for invoice aging analysis.

Enum Value Description
NO_DUE

Invoices with no due date or not yet due.

NET_30

Invoices due within 0-30 days.

NET_30_60

Invoices due within 31-60 days.

NET_60_90

Invoices due within 61-90 days.

NET_90

Invoices due more than 90 days.

"NO_DUE"

aging_report_result_item

A single result item in the aging report representing aging buckets for a specific currency-status combination.

required
Array of objects (aging_bucket) [ 1 .. 20 ] items

Aging buckets with counts and totals for this currency–status pair.

currency
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

Three-letter ISO currency code for this summary item.

status
required
string (invoice_statuses_for_aggregation) [ 1 .. 100 ] characters ^[A-Z0-9_]+$

Invoice status for this summary item.

Enum Value Description
OUTSTANDING

Invoices that are sent but not yet paid or only partially paid.

PAID

Invoices that have been fully paid.

{
  • "buckets": [
    • {
      • "from": 1000,
      • "to": 1000,
      • "count": 2147483647,
      • "label": "NO_DUE",
      • "total": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    ],
  • "currency": "str",
  • "status": "OUTSTANDING"
}

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 [ 0 .. 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"
      }
    }
}

An object representing a specific subscription plan info.

An object representing a specific subscription plan info.

id
string = 39 characters ^PI-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{8}-[0-9A...

Subscription plan Id. This is a unique Id identifying all the versions in a given set of plans.

name
string [ 1 .. 125 ] characters ^[A-Za-z0-9_ ]+$

The plan name.

{
  • "id": "stringstringstringstringstringstringstr",
  • "name": "string"
}

association_id

It is either a template ID or an invoice ID based on the type provided in the request.

string (association_id) [ 1 .. 30 ] characters ^(TEMP|INV2)-[A-Z0-9-]+$

It is either a template ID or an invoice ID based on the type provided in the request.

"string"

association_type

It is an association type, used to fetch theme details.

string (association_type) [ 1 .. 20 ] characters ^[A-Z0-9_]+$

It is an association type, used to fetch theme details.

Enum Value Description
TEMPLATE

Fetch theme details for a given template.

INVOICE

Fetch theme details for a given invoice.

"TEMPLATE"

batch_date_range

Filters between the start and end dates inclusive.

  • Both dates cannot be more than 1 month in the past.
  • Both dates cannot be more than 3 months from current date.
  • Start date should be before end date.

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

The start date of the range. Cannot be more than 1 month the past. Cannot be more than 3 months in the future. Cannot be after the end date.

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

The end date of the range. Cannot be more than 1 month the past. Cannot be more than 3 months in the future. Cannot be before the start date.

{
  • "start_date": "stringstri",
  • "end_date": "stringstri"
}

batch_task_summary

The details about the batch task.

id
string (id) = 40 characters ^(BAT-)1[0-9A-Z]{3}-[0-9A-Z]{4}-[0-9A-Z]{8}-[...

A unique id used to reference the batch task.

task_type
string (task_type) [ 1 .. 50 ] characters ^[A-Z0-9_]*$

Task type of the batch task. Used to determine the batch operation/logic to be performed.

Enum Value Description
RISK_LIMIT_RECENT

Task for processing recent records for the account in Invoicing.

RISK_LIMIT_FULL

Task for processing all records in Invoicing.

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

The task date as specified by the sender, in Internet date and time format. Date cannot be in the past.

{
  • "id": "stringstringstringstringstringstringstri",
  • "task_type": "RISK_LIMIT_RECENT",
  • "task_date": "stringstri"
}

billing_info

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

business_name
string <= 300 characters

Required. The business name of the party.

object (Name)

The name of the party.

object (Portable Postal Address (Medium-Grained))

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

Array of objects (phone_detail)

The invoice recipient's phone numbers. Extension number is not supported.

additional_info
string <= 40 characters

Any additional information about the recipient.

email_address
string (restrictive_email_address) [ 3 .. 254 ] characters ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(...

The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part.

  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

language
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

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

Business Name

The business name of the party.

business_name
string <= 300 characters

Required. The business name of the party.

{
  • "business_name": "string"
}

Color hex code

This object defines the color hex code.

string (Color hex code) [ 4 .. 7 ] characters ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

This object defines the color hex code.

"string"

conditional_rule_conditions

Defines the time-based condition that triggers the application of this conditional rule. This is expressed as a period relative to either the invoice issue date (for early payment discounts) or the invoice due date (for late payment surcharges and auto-cancellation). If the value is 'SPECIFIC_DATE', the 'effective_date' field must be provided to specify the exact date.

string (conditional_rule_conditions) [ 1 .. 50 ] characters ^[A-Z0-9_]*$

Defines the time-based condition that triggers the application of this conditional rule. This is expressed as a period relative to either the invoice issue date (for early payment discounts) or the invoice due date (for late payment surcharges and auto-cancellation). If the value is 'SPECIFIC_DATE', the 'effective_date' field must be provided to specify the exact date.

Enum Value Description
THREE_DAYS_AFTER_ISSUE_DATE

3 days after the invoice issue date.

SEVEN_DAYS_AFTER_ISSUE_DATE

7 days after the invoice issue date.

FIFTEEN_DAYS_AFTER_ISSUE_DATE

15 days after the invoice issue date.

THIRTY_DAYS_AFTER_ISSUE_DATE

30 days after the invoice issue date.

ONE_DAY_AFTER_DUE_DATE

1 day after the invoice due date.

SEVEN_DAYS_AFTER_DUE_DATE

7 days after the invoice due date.

FIFTEEN_DAYS_AFTER_DUE_DATE

15 days after the invoice due date.

THIRTY_DAYS_AFTER_DUE_DATE

30 days after the invoice due date.

SPECIFIC_DATE

A specific date. The 'effective_date' field must be used to specify the date.

"THREE_DAYS_AFTER_ISSUE_DATE"

conditional_rule_type

This enum defines what type of rule is applying for the particular invoice.

string (conditional_rule_type) [ 1 .. 30 ] characters ^[A-Z0-9_]*$

This enum defines what type of rule is applying for the particular invoice.

Enum Value Description
EARLY_PAYMENT_DISCOUNT

A discount applied if the invoice is paid before a specified date or within a certain period after the issue date.

LATE_PAYMENT_SURCHARGE

A surcharge applied if the invoice is paid after the due date or a specified period after the due date.

AUTO_CANCEL

A rule to automatically cancel the invoice if it is not paid by a specified date or a certain period after the due date.

"EARLY_PAYMENT_DISCOUNT"

conditional_rule_value_type

Type of the stored discount. Used to determine whether its percentage or absolute currency value.

string (conditional_rule_value_type) [ 1 .. 20 ] characters ^[A-Z0-9_]*$

Type of the stored discount. Used to determine whether its percentage or absolute currency value.

Enum Value Description
PERCENT

Percentage of discount used in invoice item or in an invoice.

AMOUNT

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

"PERCENT"

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.

has_conditional_rule
boolean
Default: false

Indicates whether conditional pricing rules are applied to the invoice. If true, pricing rules (such as discounts or surcharges based on specific conditions) are applied. If false, no conditional pricing rules are applied.

save_item_for_future
boolean
Default: true

Indicates whether the item should be saved for future invoices.

discount_mode_preference
string (discount_mode_preference) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Represents the user's preferred mode for creating discounts. Determines whether "One-time discount" or "Save for future invoices" is preselected when creating a new discount.

Enum Value Description
ONE_TIME

Indicates that the user prefers creating one-time discounts by default.

SAVE_FOR_FUTURE

Indicates that the user prefers saving discounts for future invoices by default.

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.

Note: This is an optional field. If you wish to customize the invoice layout using a specific template, provide a valid template ID here. You 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.

{
  • "tax_calculated_after_discount": true,
  • "tax_inclusive": false,
  • "allow_tip": false,
  • "has_conditional_rule": false,
  • "save_item_for_future": true,
  • "discount_mode_preference": "ONE_TIME",
  • "partial_payment": {
    • "allow_partial_payment": false,
    • "minimum_amount_due": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "template_id": "PayPal system template"
}

Connections

This object contains an array of connection details. It is used to load sync status for a user.

Array of objects (Connections) [ 1 .. 1000 ] items

An array of connection-level details.

{
  • "connections": [
    • {
      • "platform_name": "string",
      • "last_sync_status": "IN_PROGRESS",
      • "last_sync_time": "string"
      }
    ]
}

Connections

This lists last sync status and connection platform name.

platform_name
string [ 1 .. 64 ] characters ^.*$

The name of the platform. This property supports Unicode. The pattern is not provided because the value is defined by an external party.

last_sync_status
string [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The status of the last sync. This property supports Unicode.

Enum Value Description
IN_PROGRESS

The last sync process has started.

SUCCESS

The last sync process is success.

FAILED

The last sync process failed.

last_sync_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.

{
  • "platform_name": "string",
  • "last_sync_status": "IN_PROGRESS",
  • "last_sync_time": "string"
}

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 2-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 2-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 [ 0 .. 50 ] characters ^[\S\s]*$

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"

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"

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 [ 1 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

note
string [ 1 .. 4000 ] characters ^[\S\s]*$

A note to the invoice recipient. Also appears on the invoice notification email.

terms_and_conditions
string [ 1 .. 4000 ] characters ^[\S\s]*$

The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

memo
string [ 1 .. 500 ] characters ^[\S\s]*$

A private bookkeeping memo for the user.

Array of objects (File Reference) [ 0 .. 2147483647 ] items

An array of PayPal IDs for the files that are attached to an invoice.

Array of objects (tip_preset) [ 1 .. 3 ] items

Specifies the predefined tip options configured by the invoicer. These preset values are shown to customers at checkout as suggested tipping amounts, in addition to the option to enter a custom tip.

order_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Order details information in the invoice.

project_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Project details information in the invoice.

service_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service details information in the invoice.

cancellation_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Cancellation policy information in the invoice.

payment_terms
string [ 1 .. 2500 ] characters ^[\S\s]*$

Payment terms information in the invoice.

return_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Return policy information in the invoice.

service_agreement
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service agreement information in the 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"
      }
    ],
  • "tip_presets": [
    • {
      • "percent": "19.99"
      }
    ],
  • "order_details": "string",
  • "project_details": "string",
  • "service_details": "string",
  • "cancellation_policy": "string",
  • "payment_terms": "string",
  • "return_policy": "string",
  • "service_agreement": "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"
    }
}

discount_mode_preference

Represents the user's preferred mode for creating discounts. Determines whether "One-time discount" or "Save for future invoices" is preselected when creating a new discount.

string (discount_mode_preference) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Represents the user's preferred mode for creating discounts. Determines whether "One-time discount" or "Save for future invoices" is preselected when creating a new discount.

Enum Value Description
ONE_TIME

Indicates that the user prefers creating one-time discounts by default.

SAVE_FOR_FUTURE

Indicates that the user prefers saving discounts for future invoices by default.

"ONE_TIME"

display_preference

The display preference of the field.

hidden
boolean

Indicates whether to show or hide the field.

{
  • "hidden": true
}

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"

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"

email_status

List of delivery statuses to be sent as a part of email callback API.

string (email_status) [ 1 .. 40 ] characters ^[A-Z0-9_]+$

List of delivery statuses to be sent as a part of email callback API.

Enum Value Description
SENT

Status Sent from Notifications layer.

DELIVERED

Status delivered to the aggregator/vendor/client.

OPENED

Status for the notification opened by the end user.

FAIL_HARD

Status hard failure - Notification cannot be delivered to the end user.

FAIL_SOFT

Status soft failure - This is a temporary failure and can be retried.

CLICKED

Status for push notification clicks.

"SENT"

entity_id

It is either a merchant ID or an invoice ID based on the type provided in the request.

string (entity_id) [ 1 .. 30 ] characters ^.*$

It is either a merchant ID or an invoice ID based on the type provided in the request.

"string"

entity_type

It is an entity type, used to fetch payment method details.

string (entity_type) [ 1 .. 20 ] characters ^[A-Z0-9_]+$

It is an entity type, used to fetch payment method details.

Enum Value Description
MERCHANT

Fetch payment method details for a given merchant.

INVOICE

Fetch payment method details for a given invoice.

TEMPLATE

Fetch payment method details for a given template.

"MERCHANT"

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",
          • "title": "string",
          • "mediaType": "string",
          • "encType": "application/json",
          • "schema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            },
          • "targetSchema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            }
          }
        ]
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

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.

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",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET",
          • "title": "string",
          • "mediaType": "string",
          • "encType": "application/json",
          • "schema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            },
          • "targetSchema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            }
          }
        ],
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

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",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

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.

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.

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.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "description": "string"
}

Estimate

Estimate information, this contains the information about the estimate like item, amount, billing and shipping information.

id
string [ 1 .. 30 ] characters ^[A-Z0-9_-]+$

The ID of the estimate.

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

Represents estimate status.

Enum Value Description
DRAFT

Draft estimate.

SENT

Estimate sent.

CANCELLED

Estimate cancelled.

SHARED

Estimate shared.

ACCEPTED

Estimate accepted.

DELETED

Estimate deleted.

INVOICED

Estimate invoiced.

EXPIRED

Estimate expired.

required
object (estimate_detail)

The details of the estimate. Includes estimate number, date and audit metadata.

object (invoicer_info)

The invoicer business information that appears on the invoice.

Array of objects (recipient_info) [ 1 .. 100 ] items

The billing and shipping information. Includes name, email, address, phone and language.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) [ 1 .. 100 ] items

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

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

Array of objects (item) [ 1 .. 100 ] items

An array of estimate line item information.

object (configuration)

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

object (amount_summary_detail)

The invoice amount summary of item total, discount, tax total, and shipping.

Array of objects (Link Description) [ 1 .. 7 ] items

An array of request-related HATEOAS links.

{
  • "id": "string",
  • "status": "DRAFT",
  • "detail": {
    • "reference": "string",
    • "note": "string",
    • "terms_and_conditions": "string",
    • "memo": "string",
    • "attachments": [
      • {
        • "id": "string",
        • "reference_url": "http://example.com",
        • "content_type": "string",
        • "size": "string",
        • "create_time": "string"
        }
      ],
    • "tip_presets": [
      • {
        • "percent": "19.99"
        }
      ],
    • "order_details": "string",
    • "project_details": "string",
    • "service_details": "string",
    • "cancellation_policy": "string",
    • "payment_terms": "string",
    • "return_policy": "string",
    • "service_agreement": "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,
    • "has_conditional_rule": false,
    • "save_item_for_future": true,
    • "discount_mode_preference": "ONE_TIME",
    • "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",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

estimate_detail

The details of the estimate. Includes estimate number, date and audit metadata.

reference
string [ 1 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

note
string [ 1 .. 4000 ] characters ^[\S\s]*$

A note to the invoice recipient. Also appears on the invoice notification email.

terms_and_conditions
string [ 1 .. 4000 ] characters ^[\S\s]*$

The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

memo
string [ 1 .. 500 ] characters ^[\S\s]*$

A private bookkeeping memo for the user.

Array of objects (File Reference) [ 0 .. 2147483647 ] items

An array of PayPal IDs for the files that are attached to an invoice.

Array of objects (tip_preset) [ 1 .. 3 ] items

Specifies the predefined tip options configured by the invoicer. These preset values are shown to customers at checkout as suggested tipping amounts, in addition to the option to enter a custom tip.

order_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Order details information in the invoice.

project_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Project details information in the invoice.

service_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service details information in the invoice.

cancellation_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Cancellation policy information in the invoice.

payment_terms
string [ 1 .. 2500 ] characters ^[\S\s]*$

Payment terms information in the invoice.

return_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Return policy information in the invoice.

service_agreement
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service agreement information in the 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"
      }
    ],
  • "tip_presets": [
    • {
      • "percent": "19.99"
      }
    ],
  • "order_details": "string",
  • "project_details": "string",
  • "service_details": "string",
  • "cancellation_policy": "string",
  • "payment_terms": "string",
  • "return_policy": "string",
  • "service_agreement": "string",
  • "currency_code": "string",
  • "estimate_number": "string",
  • "viewed_by_recipient": true,
  • "estimate_date": "string",
  • "estimate_term": {
    • "term_type": "DUE_ON_RECEIPT",
    • "expiration_date": "string"
    },
  • "metadata": {
    • "created_by": "string",
    • "last_updated_by": "string",
    • "create_time": "string",
    • "last_update_time": "string",
    • "cancelled_by": "string",
    • "last_sent_by": "string",
    • "recipient_view_url": "http://example.com",
    • "invoicer_view_url": "http://example.com",
    • "cancel_time": "string",
    • "first_sent_time": "string",
    • "last_sent_time": "string",
    • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
    }
}

estimate_free_text_search_fields

Supported estimate free text search fields.

string (estimate_free_text_search_fields) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Supported estimate free text search fields.

Enum Value Description
ESTIMATE_NUMBER

Estimate number.

NOTES

Notes associated with the invoice.

MERCHANT_MEMO

Merchant memo related to the invoice.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the invoice item.

ITEM_TAX_NAME

Tax name associated with the invoice item.

ITEM_DISCOUNT_NAME

Discount name associated with the invoice item.

ESTIMATE_DISCOUNT_NAME

Discount name associated with the estimate.

ALL

Search in all available search fields.

"ESTIMATE_NUMBER"

estimate_payment_term

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

term_type
string (payment_term_type) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
DUE_ON_RECEIPT

The payment for the invoice is due upon receipt of the invoice.

DUE_ON_DATE_SPECIFIED

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

NET_10

The payment for the invoice is due in 10 days.

NET_15

The payment for the invoice is due in 15 days.

NET_30

The payment for the invoice is due in 30 days.

NET_45

The payment for the invoice is due in 45 days.

NET_60

The payment for the invoice is due in 60 days.

NET_90

The payment for the invoice is due in 90 days.

NO_DUE_DATE

The invoice has no payment due date.

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

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

{
  • "term_type": "DUE_ON_RECEIPT",
  • "expiration_date": "string"
}

estimate_status

Supported estimate status.

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

Supported estimate status.

Enum Value Description
DRAFT

Draft estimate.

SENT

Estimate sent.

CANCELLED

Estimate cancelled.

SHARED

Estimate shared.

ACCEPTED

Estimate accepted.

INVOICED

Estimate invoiced.

EXPIRED

Estimate expired.

"DRAFT"

estimate_suggestion_fields

Supported estimate suggestion fields.

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

Supported estimate suggestion fields.

Enum Value Description
ESTIMATE_NUMBER

Number associated with it.

NOTES

Notes associated with the estimate.

MERCHANT_MEMO

Merchant memo related to the estimate.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the estimate item.

ALL

This is used to search in all available search fields.

"ESTIMATE_NUMBER"

estimates

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

suggested_text
string [ 3 .. 800 ] characters ^(?!\s*$).+

Represents the text which has been provided in request.

fields
Array of strings (estimate_suggestion_fields) [ 1 .. 14 ] items unique

An array of matched estimate fields.

Items Enum Value Description
ESTIMATE_NUMBER

Number associated with it.

NOTES

Notes associated with the estimate.

MERCHANT_MEMO

Merchant memo related to the estimate.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the estimate item.

ALL

This is used to search in all available search fields.

{
  • "suggested_text": "string",
  • "fields": [
    • "ESTIMATE_NUMBER"
    ]
}

Feature Object

Represents a feature associated with the invoicing product.

code
string [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The feature code.

subscription_id
string = 39 characters ^SI-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]...

Unique identifier for the subscription associated with this feature.

status
string (The status of the feature.) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Indicates the status of the feature. If this feature is a paywall feature, it reflects the status of the associated subscription.

Enum Value Description
ACTIVE

Represents the feature is active.

CANCELLED

Represents the feature is cancelled.

PENDING_CANCELLATION

Represents the feature is in pending cancelled state.

PENDING_ACTIVATION

Represents the feature is in pending activation state.

SUSPENDED

Represents the feature is suspended.

REVOKED

Represents the feature has been revoked.

APPROVED

Represents the feature has been approved.

IN_REVIEW

Represents the feature is currently under review.

NEED_DATA

Represents the feature requires additional data.

DENY

Represents the feature has been denied.

INACTIVE

Represents the feature is inactive.

PENDING

Represents the feature is in a pending state.

type
string (The type of the feature.) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Indicates the type of the feature.

Enum Value Description
PAID

Represents the feature is a paid feature.

FREE

Represents the feature is a free feature.

{
  • "code": "string",
  • "subscription_id": "stringstringstringstringstringstringstr",
  • "status": "ACTIVE",
  • "type": "PAID"
}

Feedback Classifiers

Allows a client to tag requests for future retrieval.

tags
Array of strings [ 1 .. 10 ] items

A set of simple tags.

required
object (A set of regular JSON style properties and values.)

A set of regular JSON style properties and values.

{
  • "tags": [
    • "string"
    ],
  • "pairs": {
    • "property1": "string",
    • "property2": "string"
    }
}

feedback_data

The details about the feedback.

feedback_id
string [ 30 .. 45 ] characters ^[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}...

The feedback identifier.

reaction
required
string (reaction) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

This indicates the Customer's reaction, which can be a like or dislike.

Enum Value Description
LIKE

Customer likes the seller/goods/service.

DISLIKE

Customer dislikes the seller/goods/service.

text
string [ 1 .. 250 ] characters ^[\S\s]*$

Detailed feedback from the customer. The pattern is not provided because this property supports Unicode.

{
  • "feedback_id": "stringstringstringstringstring",
  • "reaction": "LIKE",
  • "text": "string"
}

feedback_visibility_updates

Updates the visibility of customer feedback comments, allowing merchants to hide or show specific comments.

feedback_id
required
string [ 30 .. 45 ] characters ^[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}...

The feedback identifier.

is_hidden
required
boolean
Default: false

Indicates whether the feedback is hidden to the merchant. If true, the feedback is hidden. If false, the feedback is visible.

{
  • "feedback_id": "stringstringstringstringstring",
  • "is_hidden": false
}

Feedbacks Stat

Aggregated feedback associated with an merchant basded on the type.

metric
string (metric) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

This indicates the metrics of the each dimensions we are aggregating.

Enum Value Description
LIKES_COUNT

Total number of likes for the given time period.

DISLIKES_COUNT

Total number of dislikes for the given time period.

TOTAL_FEEDBACK_COUNT

Total number of feedbacks for the given time period.

INVOICES_RATED_PERCENT

Percentage of invoice rated out of sent for the given time period.

value
string [ 1 .. 10 ] characters (\d+%?|\d+\.\d+%?)

Value of the metric it could be a number or a number with percentage as well.

change
string [ 1 .. 10 ] characters ([+-]\d+(\.\d+)?%)

Value of the metric it could be a positive or a negative number with percentage as well.

{
  • "metric": "LIKES_COUNT",
  • "value": "string",
  • "change": "string"
}

fetchtype

Is the fetch type invoice number or id.

fetch_id
boolean
Default: "false"

Optional to decide the number or ID.

{
  • "fetch_id": "false"
}

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

Get Record Count

This object contains a total record count and array of start date, end date and record count of records created between those dates.

record_count
integer [ 0 .. 2147483647 ]

Total number of records for the merchant based on the filter.

start_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.

end_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.

{
  • "record_count": 1250,
  • "start_time": "string",
  • "end_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 [ 0 .. 30 ] characters ^[\s\S]*$

The ID of the invoice.

parent_id
string [ 0 .. 30 ] characters ^[\s\S]*$

The parent ID to an invoice that defines the group invoice to which the invoice is related.

Array of objects (recipient_info) [ 0 .. 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) [ 0 .. 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) [ 0 .. 100 ] items

An array of invoice line item information.

Array of objects (Link Description) [ 0 .. 2147483647 ] items

An array of request-related HATEOAS links.

status
string (invoice_status) [ 0 .. 255 ] characters ^[\s\S]*$

The status of the invoice.

Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

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 (invoice_settings)

The settings for the invoice.

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",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "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"
        }
      ],
    • "tip_presets": [
      • {
        • "percent": "19.99"
        }
      ],
    • "order_details": "string",
    • "project_details": "string",
    • "service_details": "string",
    • "cancellation_policy": "string",
    • "payment_terms": "string",
    • "return_policy": "string",
    • "service_agreement": "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,
    • "has_conditional_rule": false,
    • "save_item_for_future": true,
    • "discount_mode_preference": "ONE_TIME",
    • "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"
          }
        }
      }
    },
  • "settings": {
    • "invoice_item_settings": [
      • {
        • "field_name": "ITEM_DESCRIPTION",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_additional_settings": [
      • {
        • "field_name": "ATTACHMENT",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_policy_and_agreement_settings": [
      • {
        • "field_name": "CANCELLATION_POLICY",
        • "display_preference": {
          • "hidden": true
          }
        }
      ],
    • "invoice_details_settings": [
      • {
        • "field_name": "ORDER_DETAILS",
        • "display_preference": {
          • "hidden": true
          }
        }
      ]
    },
  • "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",
        • "payment_date_time": "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

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

id
string [ 1 .. 30 ] characters ^[\s\S]*$

The ID of the invoice.

parent_id
string [ 1 .. 30 ] characters ^[\s\S]*$

The parent ID to an invoice that defines the group invoice to which the invoice is related.

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 invoice line item information.

Array of objects (Link Description) [ 1 .. 2147483647 ] items

An array of request-related HATEOAS links.

status
string (invoice_status) [ 0 .. 255 ] characters ^[\s\S]*$

The status of the invoice.

Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

required
object (invoice_detail)

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

object (invoicer_info)

The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

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)

List of payments registered against the invoice..

object (refunds)

List of refunds against this invoice. The invoicing refund details includes 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",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "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"
        }
      ],
    • "tip_presets": [
      • {
        • "percent": "19.99"
        }
      ],
    • "order_details": "string",
    • "project_details": "string",
    • "service_details": "string",
    • "cancellation_policy": "string",
    • "payment_terms": "string",
    • "return_policy": "string",
    • "service_agreement": "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,
    • "has_conditional_rule": false,
    • "save_item_for_future": true,
    • "discount_mode_preference": "ONE_TIME",
    • "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",
        • "payment_date_time": "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 Connection Details

Returns invoice connection status with timestamp per invoice.

id
string [ 1 .. 64 ] characters ^[A-Za-z0-9\-]+$

The ID of the invoice. This property supports Unicode.

Array of objects (Connections) [ 1 .. 1000 ] items

An array of connection-level details.

{
  • "id": "string",
  • "connection_status": [
    • {
      • "connections": [
        • {
          • "platform_name": "string",
          • "last_sync_status": "IN_PROGRESS",
          • "last_sync_time": "string"
          }
        ]
      }
    ]
}

Invoice Number

The invoice number.

invoice_number
string [ 1 .. 25 ] characters ^[\S\s]*$

The invoice number. If you omit this value, the default is the auto-incremented number from the last number.

invoice_id
string [ 1 .. 24 ] characters ^(INV2-)[A-Z0-9\-]{19}$

Resource Id.

{
  • "invoice_number": "string",
  • "invoice_id": "string"
}

invoice_additional_setting

The invoice additional setting.

field_name
string (invoice_additional_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for additional sections in the invoice.

Enum Value Description
ATTACHMENT

The file attachments added to the invoice.

MEMO

The internal memo in the invoice that is visible only to the invoicer.

REFERENCE

The reference number in the invoice for tracking or correlation.

object (display_preference)

The display preference of the field.

{
  • "field_name": "ATTACHMENT",
  • "display_preference": {
    • "hidden": true
    }
}

invoice_additional_settings_field

The field names for additional sections in the invoice.

string (invoice_additional_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for additional sections in the invoice.

Enum Value Description
ATTACHMENT

The file attachments added to the invoice.

MEMO

The internal memo in the invoice that is visible only to the invoicer.

REFERENCE

The reference number in the invoice for tracking or correlation.

"ATTACHMENT"

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) [ 0 .. 255 ] characters ^[\s\S]*$

The frequency at which the invoice is sent:

  • Multiple recipient. Sent to multiple recipients.
  • Batch. Sent in a batch.
  • Regular single. Sent one time to a single recipient.

Enum Value Description
MULTIPLE_RECIPIENTS_GROUP

The invoice sent to multiple recipients.

BATCH

The invoice sent as a batch.

REGULAR_SINGLE

The regular invoice sent to single recipient.

"MULTIPLE_RECIPIENTS_GROUP"

invoice_detail

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

reference
string [ 1 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

note
string [ 1 .. 4000 ] characters ^[\S\s]*$

A note to the invoice recipient. Also appears on the invoice notification email.

terms_and_conditions
string [ 1 .. 4000 ] characters ^[\S\s]*$

The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

memo
string [ 1 .. 500 ] characters ^[\S\s]*$

A private bookkeeping memo for the user.

Array of objects (File Reference) [ 0 .. 2147483647 ] items

An array of PayPal IDs for the files that are attached to an invoice.

Array of objects (tip_preset) [ 1 .. 3 ] items

Specifies the predefined tip options configured by the invoicer. These preset values are shown to customers at checkout as suggested tipping amounts, in addition to the option to enter a custom tip.

order_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Order details information in the invoice.

project_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Project details information in the invoice.

service_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service details information in the invoice.

cancellation_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Cancellation policy information in the invoice.

payment_terms
string [ 1 .. 2500 ] characters ^[\S\s]*$

Payment terms information in the invoice.

return_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Return policy information in the invoice.

service_agreement
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service agreement information in the 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"
      }
    ],
  • "tip_presets": [
    • {
      • "percent": "19.99"
      }
    ],
  • "order_details": "string",
  • "project_details": "string",
  • "service_details": "string",
  • "cancellation_policy": "string",
  • "payment_terms": "string",
  • "return_policy": "string",
  • "service_agreement": "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_details_setting

The invoice details setting.

field_name
string (invoice_details_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the invoice details.

Enum Value Description
ORDER_DETAILS

Order details information in the invoice.

PROJECT_DETAILS

Project details information in the invoice.

SERVICE_DETAILS

Service details information in the invoice.

object (display_preference)

The display preference of the field.

{
  • "field_name": "ORDER_DETAILS",
  • "display_preference": {
    • "hidden": true
    }
}

invoice_details_settings_field

The field names for the invoice details.

string (invoice_details_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the invoice details.

Enum Value Description
ORDER_DETAILS

Order details information in the invoice.

PROJECT_DETAILS

Project details information in the invoice.

SERVICE_DETAILS

Service details information in the invoice.

"ORDER_DETAILS"

invoice_free_text_search_fields

Supported invoice free text search fields.

string (invoice_free_text_search_fields) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Supported invoice free text search fields.

Enum Value Description
INVOICE_NUMBER

Invoice number.

NOTES

Notes associated with the invoice.

MERCHANT_MEMO

Merchant memo related to the invoice.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the invoice item.

ITEM_TAX_NAME

Tax name associated with the invoice item.

ITEM_DISCOUNT_NAME

Discount name associated with the invoice item.

TRANSACTION_ID

Transaction ID associated with the invoice payment.

GROUP_ID

Group ID associated with the invoice.

INVOICE_DISCOUNT_NAME

Discount name associated with the invoice.

ALL

Search in all available search fields (except GROUP_ID).

"INVOICE_NUMBER"

invoice_item_field

The field name for the invoice item.

string (invoice_item_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field name for the invoice item.

Enum Value Description
ITEM_DESCRIPTION

The description of the item.

ITEM_DATE

The date of the item.

ITEM_TAX

The tax of the item.

ITEM_DISCOUNT

The discount of the item.

"ITEM_DESCRIPTION"

invoice_item_setting

The invoice item setting.

field_name
string (invoice_item_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field name for the invoice item.

Enum Value Description
ITEM_DESCRIPTION

The description of the item.

ITEM_DATE

The date of the item.

ITEM_TAX

The tax of the item.

ITEM_DISCOUNT

The discount of the item.

object (display_preference)

The display preference of the field.

{
  • "field_name": "ITEM_DESCRIPTION",
  • "display_preference": {
    • "hidden": true
    }
}

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) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
DUE_ON_RECEIPT

The payment for the invoice is due upon receipt of the invoice.

DUE_ON_DATE_SPECIFIED

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

NET_10

The payment for the invoice is due in 10 days.

NET_15

The payment for the invoice is due in 15 days.

NET_30

The payment for the invoice is due in 30 days.

NET_45

The payment for the invoice is due in 45 days.

NET_60

The payment for the invoice is due in 60 days.

NET_90

The payment for the invoice is due in 90 days.

NO_DUE_DATE

The invoice has no payment due date.

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

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

{
  • "term_type": "DUE_ON_RECEIPT",
  • "due_date": "string"
}

invoice_policy_and_agreement_setting

The invoice policy and agreement setting.

field_name
string (invoice_policy_and_agreement_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the policy and agreement details in the invoice.

Enum Value Description
CANCELLATION_POLICY

Cancellation policy information in the invoice.

PAYMENT_TERMS

Payment terms information in the invoice.

RETURN_POLICY

Return policy information in the invoice.

SERVICE_AGREEMENT

Service agreement information in the invoice.

TERMS_AND_CONDITIONS

Terms and conditions information in the invoice.

object (display_preference)

The display preference of the field.

{
  • "field_name": "CANCELLATION_POLICY",
  • "display_preference": {
    • "hidden": true
    }
}

invoice_policy_and_agreement_settings_field

The field names for the policy and agreement details in the invoice.

string (invoice_policy_and_agreement_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the policy and agreement details in the invoice.

Enum Value Description
CANCELLATION_POLICY

Cancellation policy information in the invoice.

PAYMENT_TERMS

Payment terms information in the invoice.

RETURN_POLICY

Return policy information in the invoice.

SERVICE_AGREEMENT

Service agreement information in the invoice.

TERMS_AND_CONDITIONS

Terms and conditions information in the invoice.

"CANCELLATION_POLICY"

invoice_settings

The settings for the invoice.

Array of objects (invoice_item_setting) [ 1 .. 10 ] items

The settings for the invoice items.

Array of objects (invoice_additional_setting) [ 1 .. 10 ] items

The settings for the invoice additional fields.

Array of objects (invoice_policy_and_agreement_setting) [ 1 .. 10 ] items

The settings for the invoice policy and agreement fields.

Array of objects (invoice_details_setting) [ 1 .. 10 ] items

The settings for the invoice details fields.

{
  • "invoice_item_settings": [
    • {
      • "field_name": "ITEM_DESCRIPTION",
      • "display_preference": {
        • "hidden": true
        }
      }
    ],
  • "invoice_additional_settings": [
    • {
      • "field_name": "ATTACHMENT",
      • "display_preference": {
        • "hidden": true
        }
      }
    ],
  • "invoice_policy_and_agreement_settings": [
    • {
      • "field_name": "CANCELLATION_POLICY",
      • "display_preference": {
        • "hidden": true
        }
      }
    ],
  • "invoice_details_settings": [
    • {
      • "field_name": "ORDER_DETAILS",
      • "display_preference": {
        • "hidden": true
        }
      }
    ]
}

invoice_status

The status of the invoice.

string (invoice_status) [ 0 .. 255 ] characters ^[\s\S]*$

The status of the invoice.

Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

"DRAFT"

invoice_statuses_for_aggregation

Status of the invoice enum for aggregation purposes.

string (invoice_statuses_for_aggregation) [ 1 .. 100 ] characters ^[A-Z0-9_]+$

Status of the invoice enum for aggregation purposes.

Enum Value Description
OUTSTANDING

Invoices that are sent but not yet paid or only partially paid.

PAID

Invoices that have been fully paid.

"OUTSTANDING"

invoice_suggestion_fields

Supported invoice suggestion fields.

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

Supported invoice suggestion fields.

Enum Value Description
INVOICE_NUMBER

Number associated with it.

NOTES

Notes associated with the invoice.

MERCHANT_MEMO

Merchant memo related to the invoice.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the invoice item.

TRANSACTION_ID

Transaction ID associated with the invoice payment.

ALL

This is used to search in all available search fields.

"INVOICE_NUMBER"

invoicer_info

The invoicer business information that appears on the invoice.

business_name
string <= 300 characters

Required. The business name of the party.

object (Name)

The name of the party.

object (Portable Postal Address (Medium-Grained))

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

Array of objects (phone_detail)

An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.

website
string <uri> <= 2048 characters

The invoicer's website.

tax_id
string <= 100 characters

The invoicer's tax ID.

additional_notes
string <= 400 characters

Any additional information. Includes business hours.

logo_url
string <uri> <= 2000 characters

The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.

email_address
string (restrictive_email_address) [ 3 .. 254 ] characters ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(...

The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part.

  • Allows alphanumeric and RFC-allowed special characters, !#$%&'*+-/=?^_`{|}~
  • Ensures that the local part does not start with dot (.), have consecutive dots, or end with dot. Ensures that the domain part does not have consecutive dots.
  • Ensures that the local part does not exceed 64 characters.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

{
  • "business_name": "string",
  • "name": {
    • "prefix": "string",
    • "given_name": "string",
    • "surname": "string",
    • "middle_name": "string",
    • "suffix": "string",
    • "alternate_full_name": "string",
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      }
    },
  • "phones": [
    • {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string",
      • "phone_type": "FAX"
      }
    ],
  • "website": "http://example.com",
  • "tax_id": "string",
  • "additional_notes": "string",
  • "logo_url": "http://example.com",
  • "email_address": "string"
}

invoices

An array of merchant invoices. Includes the total invoices count and HATEOAS links for navigation.

total_pages
integer [ 0 .. 2147483647 ]

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 [ 0 .. 2147483647 ]

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) [ 0 .. 100 ] items

The list of invoices that match the search criteria.

Array of objects (Link Description) [ 0 .. 2147483647 ] items

An array of request-related HATEOAS links.

{
  • "total_pages": 2147483647,
  • "total_items": 2147483647,
  • "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",
          • "title": "string",
          • "mediaType": "string",
          • "encType": "application/json",
          • "schema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            },
          • "targetSchema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            }
          }
        ],
      • "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"
            }
          ],
        • "tip_presets": [
          • {
            • "percent": "19.99"
            }
          ],
        • "order_details": "string",
        • "project_details": "string",
        • "service_details": "string",
        • "cancellation_policy": "string",
        • "payment_terms": "string",
        • "return_policy": "string",
        • "service_agreement": "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,
        • "has_conditional_rule": false,
        • "save_item_for_future": true,
        • "discount_mode_preference": "ONE_TIME",
        • "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"
              }
            }
          }
        },
      • "settings": {
        • "invoice_item_settings": [
          • {
            • "field_name": "ITEM_DESCRIPTION",
            • "display_preference": {
              • "hidden": true
              }
            }
          ],
        • "invoice_additional_settings": [
          • {
            • "field_name": "ATTACHMENT",
            • "display_preference": {
              • "hidden": true
              }
            }
          ],
        • "invoice_policy_and_agreement_settings": [
          • {
            • "field_name": "CANCELLATION_POLICY",
            • "display_preference": {
              • "hidden": true
              }
            }
          ],
        • "invoice_details_settings": [
          • {
            • "field_name": "ORDER_DETAILS",
            • "display_preference": {
              • "hidden": true
              }
            }
          ]
        },
      • "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",
            • "payment_date_time": "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",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

invoices

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

suggested_text
string [ 3 .. 800 ] characters ^(?!\s*$).+

Represents the text which has been provided in request.

fields
Array of strings (invoice_suggestion_fields) [ 1 .. 14 ] items unique

An array of matched invoice fields.

Items Enum Value Description
INVOICE_NUMBER

Number associated with it.

NOTES

Notes associated with the invoice.

MERCHANT_MEMO

Merchant memo related to the invoice.

PAYER_REFERENCE_INFO

Payer's reference information.

BILLING_EMAIL

Email address associated with billing.

BILLING_NAME

Name associated with billing.

BILLING_BUSINESS_NAME

Business name associated with billing.

BILLING_PHONE_NUMBER

Phone number associated with billing.

SHIPPING_EMAIL

Email address associated with shipping.

SHIPPING_NAME

Name associated with shipping.

SHIPPING_BUSINESS_NAME

Business name associated with shipping.

SHIPPING_PHONE_NUMBER

Phone number associated with shipping.

ITEM_NAME

Name of the invoice item.

TRANSACTION_ID

Transaction ID associated with the invoice payment.

ALL

This is used to search in all available search fields.

{
  • "suggested_text": "string",
  • "fields": [
    • "INVOICE_NUMBER"
    ]
}

item

An array of invoice line item information. The maximum items for an invoice is 100.

id
string [ 0 .. 22 ] characters ^[\S\s]*$

The ID of the invoice line item.

name
required
string [ 0 .. 200 ] characters ^[\S\s]*$

The item name for the invoice line item.

description
string [ 0 .. 1000 ] characters ^[\S\s]*$

The item description for the invoice line item.

quantity
required
string [ 0 .. 14 ] characters \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.

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) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unit of measure for the invoiced item. For AMOUNT the unit_amount and quantity are not shown on the invoice.

Note: If your specify different unit_of_measure values for the same invoice, the invoice uses the first value.

Enum Value Description
QUANTITY

The unit of measure is quantity. This invoice template is typically used for physical goods.

HOURS

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

AMOUNT

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

{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "quantity": "string",
  • "unit_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "tax_note": "string",
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "item_date": "string",
  • "discount": {
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "unit_of_measure": "QUANTITY"
}

language

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

"string"

layout

Supported invoice layouts.

string (layout) [ 1 .. 155 ] characters ^[A-Z0-9_]+$

Supported invoice layouts.

Enum Value Description
CLASSIC

Default classic invoice layout.

BRANDED

Customised invoice layout.

"CLASSIC"

metadata

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

created_by
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The email address of the account that created the resource.

last_updated_by
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

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) [ 0 .. 255 ] characters ^[\s\S]*$

The flow variation that created this invoice.

Enum Value Description
MULTIPLE_RECIPIENTS_GROUP

The invoice sent to multiple recipients.

BATCH

The invoice sent as a batch.

REGULAR_SINGLE

The regular invoice sent to single recipient.

{
  • "created_by": "string",
  • "last_updated_by": "string",
  • "create_time": "string",
  • "last_update_time": "string",
  • "cancelled_by": "string",
  • "last_sent_by": "string",
  • "recipient_view_url": "http://example.com",
  • "invoicer_view_url": "http://example.com",
  • "cancel_time": "string",
  • "first_sent_time": "string",
  • "last_sent_time": "string",
  • "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP"
}

metric

This indicates the metrics of the each dimensions we are aggregating.

string (metric) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

This indicates the metrics of the each dimensions we are aggregating.

Enum Value Description
LIKES_COUNT

Total number of likes for the given time period.

DISLIKES_COUNT

Total number of dislikes for the given time period.

TOTAL_FEEDBACK_COUNT

Total number of feedbacks for the given time period.

INVOICES_RATED_PERCENT

Percentage of invoice rated out of sent for the given time period.

"LIKES_COUNT"

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 [ 0 .. 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 [ 0 .. 4000 ] characters ^[\S\s]*$

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

Note: User-provided values for this field will not be honored and the subject will always be defaulted to a system-defined value.

note
string [ 0 .. 4000 ] characters ^[\S\s]*$

A note to the payer.

Note: User-provided values for this field will not be honored and the note will always be defaulted to a system-defined value.

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) [ 0 .. 100 ] items

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

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

{
  • "subject": "string",
  • "note": "string",
  • "send_to_invoicer": false,
  • "send_to_recipient": true,
  • "additional_recipients": [
    • "string"
    ]
}

partial_payment

The partial payment details. Includes the minimum amount that the invoicer expects from the payer.

allow_partial_payment
boolean
Default: false

Indicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.

Note: This feature is not available for users in India, Brazil, or Israel.

object (Money)

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

{
  • "allow_partial_payment": false,
  • "minimum_amount_due": {
    • "currency_code": "str",
    • "value": "string"
    }
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum Value Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

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

replace

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

move

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

copy

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

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

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

value
any (Patch Value)

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

from
string

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

{
  • "op": "add",
  • "path": "string",
  • "value": null,
  • "from": "string"
}

payables_summary_item

A single summary item representing aggregated payables data for a specific currency-status combination.

count
required
integer [ 0 .. 2147483647 ]

Total number of invoices matching this currency-status combination.

currency
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

Three-letter ISO currency code for this summary item.

status
required
string (invoice_statuses_for_aggregation) [ 1 .. 100 ] characters ^[A-Z0-9_]+$

Invoice status for this summary item.

Enum Value Description
OUTSTANDING

Invoices that are sent but not yet paid or only partially paid.

PAID

Invoices that have been fully paid.

required
object (Money)

Total monetary amount for invoices in this currency-status combination.

change_percentage
string <ppaas_common_percentage_v2> (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Percentage change in total amount compared to the previous period for this currency-status combination. Null if no previous period data is available.

{
  • "count": 2147483647,
  • "currency": "str",
  • "status": "OUTSTANDING",
  • "total_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "change_percentage": "string"
}

payables_summary_period

Time period for the summary report.

string (payables_summary_period) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Time period for the summary report.

Enum Value Description
LAST_30_DAYS

Summary for the last 30 days.

THIS_WEEK

Summary for the current week.

THIS_MONTH

Summary for the current month.

THIS_QUARTER

Summary for the current quarter.

THIS_YEAR

Summary for the current year.

CUSTOM

Custom date range specified by from and to parameters.

"LAST_30_DAYS"

payment_detail

The payment details of the invoice. Includes payment type, method, date, discount, and transaction type.

payment_id
string [ 0 .. 22 ] characters ^[\S\s]*$

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

note
string [ 0 .. 2000 ] characters ^[\S\s]*$

A note associated with an external cash or check payment.

type
string (payment_type) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
PAYPAL

The payment type is PayPal.

EXTERNAL

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

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

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

payment_date_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.

method
required
string (payment_method) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

object (Money)

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

object (contact_information)

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

{
  • "payment_id": "string",
  • "note": "string",
  • "type": "PAYPAL",
  • "payment_date": "string",
  • "payment_date_time": "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) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

"BANK_TRANSFER"

payment_method_detail

The details about payment methods.

payment_method_type
string (payment_method_type) [ 1 .. 120 ] characters ^[A-Z0-9_]*$

Defines the type of payment method available for invoice payment.

Enum Value Description
PAYPAL

PayPal digital wallet payment method.

ACH

Automated Clearing House (ACH) payment method.

enabled
boolean

Indicates whether the particular payment method is enabled or not.

display_order
integer [ 1 .. 100 ]

The display order of the payment method.

Array of objects (rules) [ 1 .. 10 ] items

The list of payment method rules created by the merchant.

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]|...

Indicates time of rule creation.

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]|...

Indicates time of rule updation.

{
  • "payment_method_type": "PAYPAL",
  • "enabled": true,
  • "display_order": 1,
  • "rules": [
    • {
      • "rule_type": "ALLOW_ONLY_ACH",
      • "rule_value": "string",
      • "active": true
      }
    ],
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

payment_method_rule_type

Defines the type of payment method rule applied to the invoice.

string (payment_method_rule_type) [ 1 .. 150 ] characters ^[A-Z0-9_]*$

Defines the type of payment method rule applied to the invoice.

Value Description
ALLOW_ONLY_ACH

Rule that allows only ACH payment methods.

"ALLOW_ONLY_ACH"

payment_method_type

Defines the type of payment method available for invoice payment.

string (payment_method_type) [ 1 .. 120 ] characters ^[A-Z0-9_]*$

Defines the type of payment method available for invoice payment.

Enum Value Description
PAYPAL

PayPal digital wallet payment method.

ACH

Automated Clearing House (ACH) payment method.

"PAYPAL"

payment_reference

The reference to the payment detail.

payment_id
string [ 1 .. 22 ] characters ^[0-9A-Za-z_-]+$

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) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
DUE_ON_RECEIPT

The payment for the invoice is due upon receipt of the invoice.

DUE_ON_DATE_SPECIFIED

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

NET_10

The payment for the invoice is due in 10 days.

NET_15

The payment for the invoice is due in 15 days.

NET_30

The payment for the invoice is due in 30 days.

NET_45

The payment for the invoice is due in 45 days.

NET_60

The payment for the invoice is due in 60 days.

NET_90

The payment for the invoice is due in 90 days.

NO_DUE_DATE

The invoice has no payment due date.

{
  • "term_type": "DUE_ON_RECEIPT"
}

payment_term_type

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

string (payment_term_type) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
DUE_ON_RECEIPT

The payment for the invoice is due upon receipt of the invoice.

DUE_ON_DATE_SPECIFIED

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

NET_10

The payment for the invoice is due in 10 days.

NET_15

The payment for the invoice is due in 15 days.

NET_30

The payment for the invoice is due in 30 days.

NET_45

The payment for the invoice is due in 45 days.

NET_60

The payment for the invoice is due in 60 days.

NET_90

The payment for the invoice is due in 90 days.

NO_DUE_DATE

The invoice has no payment due date.

"DUE_ON_RECEIPT"

payment_type

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

string (payment_type) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
PAYPAL

The payment type is PayPal.

EXTERNAL

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

"PAYPAL"

payments

An array of payments registered against the invoice.

Array of objects (payment_detail) [ 0 .. 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",
      • "payment_date_time": "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 Value Description
FAX

Fax number.

HOME

Home phone number.

MOBILE

Mobile phone number.

OTHER

Other phone number.

PAGER

Pager number.

"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 Value Description
FAX

Fax number.

HOME

Home phone number.

MOBILE

Mobile phone number.

OTHER

Other phone number.

PAGER

Pager number.

{
  • "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 [ 0 .. 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"
}

reaction

This indicates the Customer's reaction, which can be a like or dislike.

string (reaction) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

This indicates the Customer's reaction, which can be a like or dislike.

Enum Value Description
LIKE

Customer likes the seller/goods/service.

DISLIKE

Customer dislikes the seller/goods/service.

"LIKE"

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 [ 0 .. 22 ] characters ^[\S\s]*$

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

type
string (payment_type) [ 0 .. 255 ] characters ^[\S\s]*$

The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.

Enum Value Description
PAYPAL

The payment type is PayPal.

EXTERNAL

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

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

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

object (Money)

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

method
required
string (payment_method) [ 0 .. 255 ] characters ^[\S\s]*$

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

Enum Value Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

{
  • "refund_id": "string",
  • "type": "PAYPAL",
  • "refund_date": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "method": "BANK_TRANSFER"
}

refund_reference

The reference to the refund payment detail.

refund_id
string [ 1 .. 22 ] characters ^[0-9A-Za-z_-]+$

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) [ 0 .. 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"

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"

rules

The details about rules applied by the merchant.

discount_id
string (Stored Discount ID) [ 1 .. 22 ] characters ^DISC-[A-Z0-9]+$

A unique id used to reference the stored discount.

discount_name
string [ 1 .. 40 ] characters ^[a-zA-Z0-9\s]+$

Represents the name of the stored discount.

conditional_rule_type
required
string (conditional_rule_type) [ 1 .. 30 ] characters ^[A-Z0-9_]*$

This enum defines what type of rule is applying for the particular invoice.

Enum Value Description
EARLY_PAYMENT_DISCOUNT

A discount applied if the invoice is paid before a specified date or within a certain period after the issue date.

LATE_PAYMENT_SURCHARGE

A surcharge applied if the invoice is paid after the due date or a specified period after the due date.

AUTO_CANCEL

A rule to automatically cancel the invoice if it is not paid by a specified date or a certain period after the due date.

conditional_rule_value_type
string (conditional_rule_value_type) [ 1 .. 20 ] characters ^[A-Z0-9_]*$

Type of the stored discount. Used to determine whether its percentage or absolute currency value.

Enum Value Description
PERCENT

Percentage of discount used in invoice item or in an invoice.

AMOUNT

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

conditional_rule_value
string [ 1 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Represents the value of the conditional rule 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.

condition
required
string (conditional_rule_conditions) [ 1 .. 50 ] characters ^[A-Z0-9_]*$

Defines the time-based condition that triggers the application of this conditional rule. This is expressed as a period relative to either the invoice issue date (for early payment discounts) or the invoice due date (for late payment surcharges and auto-cancellation). If the value is 'SPECIFIC_DATE', the 'effective_date' field must be provided to specify the exact date.

Enum Value Description
THREE_DAYS_AFTER_ISSUE_DATE

3 days after the invoice issue date.

SEVEN_DAYS_AFTER_ISSUE_DATE

7 days after the invoice issue date.

FIFTEEN_DAYS_AFTER_ISSUE_DATE

15 days after the invoice issue date.

THIRTY_DAYS_AFTER_ISSUE_DATE

30 days after the invoice issue date.

ONE_DAY_AFTER_DUE_DATE

1 day after the invoice due date.

SEVEN_DAYS_AFTER_DUE_DATE

7 days after the invoice due date.

FIFTEEN_DAYS_AFTER_DUE_DATE

15 days after the invoice due date.

THIRTY_DAYS_AFTER_DUE_DATE

30 days after the invoice due date.

SPECIFIC_DATE

A specific date. The 'effective_date' field must be used to specify the date.

is_active
boolean

Indicates whether the particular rule is active or not.

is_currently_applicable
boolean

Indicates whether this rule is currently applicable based on the effective date and time relative to the invoice dates.

is_applied
boolean

Indicates whether the particular rule is applied or not.

conditional_rule_id
string <ppaas_time_based_uuid_v1> (time_based_uuid) = 36 characters ^[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}...

The time based universally unique identifier (UUID) in Universally Unique IDentifier (UUID) URN Namespace format.

effective_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 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.

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]|...

Indicates time of rule creation.

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]|...

Indicates time of rules updation.

{
  • "discount_id": "string",
  • "discount_name": "string",
  • "conditional_rule_type": "EARLY_PAYMENT_DISCOUNT",
  • "conditional_rule_value_type": "PERCENT",
  • "conditional_rule_value": "string",
  • "condition": "THREE_DAYS_AFTER_ISSUE_DATE",
  • "is_active": true,
  • "is_currently_applicable": true,
  • "is_applied": true,
  • "conditional_rule_id": "string",
  • "effective_date": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

rules

The details about payment method rules applied by the merchant.

rule_type
required
string (payment_method_rule_type) [ 1 .. 150 ] characters ^[A-Z0-9_]*$

Defines the type of payment method rule applied to the invoice.

Value Description
ALLOW_ONLY_ACH

Rule that allows only ACH payment methods.

rule_value
required
string [ 1 .. 100 ] characters ^[a-zA-Z0-9\s,.]+$

Represents the value of the payment method rule it can be amount or country.

active
boolean
Default: true

Indicates whether the rule is active or inactive. Default is true.

{
  • "rule_type": "ALLOW_ONLY_ACH",
  • "rule_value": "string",
  • "active": true
}

Search filters properties.

Search filters - to retrieve invoices.

Note:This API currently supports only one criterion for range queries, so specify only one of the following criteria: invoice_date_range, due_date_range, or payment_date_range.

currency_code
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

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

An array of invoice status.

Items Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

archived
boolean

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

object (Date and Time Range)

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

object (amount_range)

The amount range.

object (date_range)

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

object (date_range)

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

object (Date and Time Range)

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

{
  • "currency_code": "str",
  • "status": [
    • "DRAFT"
    ],
  • "archived": true,
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "invoice_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "due_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "payment_date_range": {
    • "start": "string",
    • "end": "string"
    }
}

Search filters properties.

Search filters - to retrieve estimates.

currency_code
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

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

An array of estimate status.

Items Enum Value Description
DRAFT

Draft estimate.

SENT

Estimate sent.

CANCELLED

Estimate cancelled.

SHARED

Estimate shared.

ACCEPTED

Estimate accepted.

INVOICED

Estimate invoiced.

EXPIRED

Estimate expired.

archived
boolean

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

object (Date and Time Range)

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

object (amount_range)

The amount range.

object (date_range)

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

{
  • "currency_code": "str",
  • "status": [
    • "DRAFT"
    ],
  • "archived": true,
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "estimate_date_range": {
    • "start": "string",
    • "end": "string"
    }
}

search_data

The invoice search parameters.

recipient_email
string [ 0 .. 254 ] characters ^[\S\s]*$

Filters the search by the email address.

recipient_first_name
string [ 0 .. 140 ] characters ^[\S\s]*$

Filters the search by the recipient first name.

recipient_last_name
string [ 0 .. 140 ] characters ^[\S\s]*$

Filters the search by the recipient last name.

recipient_business_name
string [ 0 .. 300 ] characters ^[\S\s]*$

Filters the search by the recipient business name.

invoice_number
string [ 0 .. 25 ] characters ^[\S\s]*$

Filters the search by the invoice number.

status
Array of strings (invoice_status) [ 0 .. 5 ] items

An array of status values.

Items Enum Value Description
DRAFT

The invoice is in draft state. It is not yet sent to the payer.

SENT

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

SCHEDULED

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

PAID

The payer has paid for the invoice.

MARKED_AS_PAID

The invoice is marked as paid by the invoicer.

CANCELLED

The invoice has been cancelled by the invoicer.

REFUNDED

The invoice has been refunded by the invoicer.

PARTIALLY_PAID

The payer has partially paid for the invoice.

PARTIALLY_REFUNDED

The invoice has been partially refunded by the invoicer.

MARKED_AS_REFUNDED

The invoice is marked as refunded by the invoicer.

UNPAID

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

PAYMENT_PENDING

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

AUTO_CANCELLED

The invoice was automatically cancelled because the payment was not received within the specified timeframe.

PAID_EXTERNAL

The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means.

REFUNDED_EXTERNAL

The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow.

SHARED

The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal.

reference
string [ 0 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

memo
string [ 0 .. 500 ] characters ^[\S\s]*$

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 [ 0 .. 5 ] items

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

currency_code
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

object (amount_range)

The amount range.

object (date_range)

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

object (date_range)

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

object (Date and Time Range)

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

{
  • "recipient_email": "string",
  • "recipient_first_name": "string",
  • "recipient_last_name": "string",
  • "recipient_business_name": "string",
  • "invoice_number": "string",
  • "status": [
    • "DRAFT"
    ],
  • "reference": "string",
  • "memo": "string",
  • "payment_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "archived": true,
  • "fields": [
    • "string"
    ],
  • "currency_code": "string",
  • "total_amount_range": {
    • "lower_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "upper_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "invoice_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "due_date_range": {
    • "start": "string",
    • "end": "string"
    },
  • "creation_date_range": {
    • "start": "string",
    • "end": "string"
    }
}

shipping_cost

The shipping fee for all items. Includes tax on shipping.

object (Money)

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

object (tax)

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

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax": {
    • "name": "string",
    • "tax_note": "string",
    • "percent": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}

stored_discount

The details about the stored discount.

id
string (id) = 40 characters ^(BAT-)1[0-9A-Z]{3}-[0-9A-Z]{4}-[0-9A-Z]{8}-[...

A unique id used to reference the batch task.

name
required
string [ 1 .. 40 ] characters ^[a-zA-Z0-9\s]+$

Represents the name of the stored discount.

value
required
string [ 1 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Represents the value of the stored discount it can be a percentage or absolute value. In case of absolute value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

type
required
string (type) [ 1 .. 20 ] characters ^[A-Z0-9_]*$

Type of the stored discount. Used to determine wheather its percentage or absolute currency value.

Enum Value Description
PERCENT

Percentage of discount used in invoice item or in an invoice.

AMOUNT

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

active
boolean

Indicates whether given stored discount is active or not.

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

Indicates time of stored discount creation.

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

Indicates time of stored discount updation.

{
  • "id": "stringstringstringstringstringstringstri",
  • "name": "string",
  • "value": "string",
  • "type": "PERCENT",
  • "active": true,
  • "created_time": "stringstringstringst",
  • "updated_time": "stringstringstringst"
}

Subscription Info

Detailed information about a subscription.

id
string = 39 characters ^SI-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]...

Identifier of the subscription.

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

The subscription status.

Enum Value Description
ACTIVE

Represents the subscription is created.

CANCELLED

Represents the subscription is cancelled.

PENDING_CANCELLATION

Represents the subscription is in pending cancelled state.

PENDING_ACTIVATION

Represents the subscription is in pending activation state.

TRIAL

Represents the subscription status is in TRIAL.

object (An object representing a specific subscription plan info.)

An object representing a specific subscription plan info.

next_billing_date_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 subscription plan next billing date time.

{
  • "id": "stringstringstringstringstringstringstr",
  • "status": "ACTIVE",
  • "plan": {
    • "id": "stringstringstringstringstringstringstr",
    • "name": "string"
    },
  • "next_billing_date_time": "string"
}

Subscription status

The subscription status.

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

The subscription status.

Enum Value Description
ACTIVE

Represents the subscription is created.

CANCELLED

Represents the subscription is cancelled.

PENDING_CANCELLATION

Represents the subscription is in pending cancelled state.

PENDING_ACTIVATION

Represents the subscription is in pending activation state.

TRIAL

Represents the subscription status is in TRIAL.

"ACTIVE"

task_type

Task type of the batch task. Used to determine the batch operation/logic to be performed.

string (task_type) [ 1 .. 50 ] characters ^[A-Z0-9_]*$

Task type of the batch task. Used to determine the batch operation/logic to be performed.

Enum Value Description
RISK_LIMIT_RECENT

Task for processing recent records for the account in Invoicing.

RISK_LIMIT_FULL

Task for processing all records in Invoicing.

"RISK_LIMIT_RECENT"

tax

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

name
required
string [ 0 .. 100 ] characters ^[\s\S]*$

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 [ 0 .. 30 ] characters ^[\S\s]*$

The ID of the template.

name
string [ 1 .. 500 ] characters ^[\S\s]*$

The template name.

Note: The template name must be unique.

description
string [ 1 .. 160 ] characters ^[\S\s]*$

The detailed description of the template.

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) [ 0 .. 2147483647 ] items

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) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unit of measure for the invoiced item.

Enum Value Description
QUANTITY

The unit of measure is quantity. This invoice template is typically used for physical goods.

HOURS

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

AMOUNT

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

{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "default_template": true,
  • "standard_template": true,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "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"
          }
        ],
      • "tip_presets": [
        • {
          • "percent": "19.99"
          }
        ],
      • "order_details": "string",
      • "project_details": "string",
      • "service_details": "string",
      • "cancellation_policy": "string",
      • "payment_terms": "string",
      • "return_policy": "string",
      • "service_agreement": "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,
      • "has_conditional_rule": false,
      • "save_item_for_future": true,
      • "discount_mode_preference": "ONE_TIME",
      • "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
          }
        }
      ],
    • "template_details_settings": [
      • {
        • "display_preference": {
          • "hidden": true
          },
        • "field_name": "ORDER_DETAILS"
        }
      ],
    • "template_policy_and_agreement_settings": [
      • {
        • "display_preference": {
          • "hidden": true
          },
        • "field_name": "CANCELLATION_POLICY"
        }
      ],
    • "template_additional_settings": [
      • {
        • "display_preference": {
          • "hidden": true
          },
        • "field_name": "ATTACHMENT"
        }
      ]
    },
  • "unit_of_measure": "QUANTITY"
}

template_additional_setting

The template additional setting. Includes the field name and display preference.

object (template_setting_display_preference)

The template setting display preference.

field_name
string (template_additional_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Indicates which field or section of the invoice template this display preference applies to, as defined in template_additional_settings_field.json.

Enum Value Description
ATTACHMENT

The file attachments added to the invoice template.

MEMO

The internal memo in the invoice template that is visible only to the invoicer.

REFERENCE

The reference number in the invoice template for tracking or correlation.

{
  • "display_preference": {
    • "hidden": true
    },
  • "field_name": "ATTACHMENT"
}

template_additional_settings_field

The field names in the invoice template for additional sections, such as reference, attachments, or memo.

string (template_additional_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names in the invoice template for additional sections, such as reference, attachments, or memo.

Enum Value Description
ATTACHMENT

The file attachments added to the invoice template.

MEMO

The internal memo in the invoice template that is visible only to the invoicer.

REFERENCE

The reference number in the invoice template for tracking or correlation.

"ATTACHMENT"

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.

has_conditional_rule
boolean
Default: false

Indicates whether conditional pricing rules are applied to the invoice. If true, pricing rules (such as discounts or surcharges based on specific conditions) are applied. If false, no conditional pricing rules are applied.

save_item_for_future
boolean
Default: true

Indicates whether the item should be saved for future invoices.

discount_mode_preference
string (discount_mode_preference) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Represents the user's preferred mode for creating discounts. Determines whether "One-time discount" or "Save for future invoices" is preselected when creating a new discount.

Enum Value Description
ONE_TIME

Indicates that the user prefers creating one-time discounts by default.

SAVE_FOR_FUTURE

Indicates that the user prefers saving discounts for future invoices by default.

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,
  • "has_conditional_rule": false,
  • "save_item_for_future": true,
  • "discount_mode_preference": "ONE_TIME",
  • "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 [ 1 .. 120 ] characters ^[\S\s]*$

The reference data. Includes a Purchase Order (PO) number.

note
string [ 1 .. 4000 ] characters ^[\S\s]*$

A note to the invoice recipient. Also appears on the invoice notification email.

terms_and_conditions
string [ 1 .. 4000 ] characters ^[\S\s]*$

The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.

memo
string [ 1 .. 500 ] characters ^[\S\s]*$

A private bookkeeping memo for the user.

Array of objects (File Reference) [ 0 .. 2147483647 ] items

An array of PayPal IDs for the files that are attached to an invoice.

Array of objects (tip_preset) [ 1 .. 3 ] items

Specifies the predefined tip options configured by the invoicer. These preset values are shown to customers at checkout as suggested tipping amounts, in addition to the option to enter a custom tip.

order_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Order details information in the invoice.

project_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Project details information in the invoice.

service_details
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service details information in the invoice.

cancellation_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Cancellation policy information in the invoice.

payment_terms
string [ 1 .. 2500 ] characters ^[\S\s]*$

Payment terms information in the invoice.

return_policy
string [ 1 .. 2500 ] characters ^[\S\s]*$

Return policy information in the invoice.

service_agreement
string [ 1 .. 2500 ] characters ^[\S\s]*$

Service agreement information in the 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"
      }
    ],
  • "tip_presets": [
    • {
      • "percent": "19.99"
      }
    ],
  • "order_details": "string",
  • "project_details": "string",
  • "service_details": "string",
  • "cancellation_policy": "string",
  • "payment_terms": "string",
  • "return_policy": "string",
  • "service_agreement": "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_details_setting

The template invoice details setting. Includes the field name and display preference for order, project, and service details.

object (template_setting_display_preference)

The template setting display preference.

field_name
string (template_details_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field name for which to map corresponding display preferences.

Enum Value Description
ORDER_DETAILS

Order details information in the invoice template.

PROJECT_DETAILS

Project details information in the invoice template.

SERVICE_DETAILS

Service details information in the invoice template.

{
  • "display_preference": {
    • "hidden": true
    },
  • "field_name": "ORDER_DETAILS"
}

template_details_settings_field

The field names for the invoice details in the template.

string (template_details_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the invoice details in the template.

Enum Value Description
ORDER_DETAILS

Order details information in the invoice template.

PROJECT_DETAILS

Project details information in the invoice template.

SERVICE_DETAILS

Service details information in the invoice template.

"ORDER_DETAILS"

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) [ 0 .. 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) [ 0 .. 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) [ 0 .. 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"
        }
      ],
    • "tip_presets": [
      • {
        • "percent": "19.99"
        }
      ],
    • "order_details": "string",
    • "project_details": "string",
    • "service_details": "string",
    • "cancellation_policy": "string",
    • "payment_terms": "string",
    • "return_policy": "string",
    • "service_agreement": "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,
    • "has_conditional_rule": false,
    • "save_item_for_future": true,
    • "discount_mode_preference": "ONE_TIME",
    • "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) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The field names for the invoice line items in the template.

Enum Value Description
ITEMS_QUANTITY

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

ITEMS_DESCRIPTION

The description of the item in the invoice template.

ITEMS_DATE

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

ITEMS_DISCOUNT

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

ITEMS_TAX

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

"ITEMS_QUANTITY"

template_item_setting

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

field_name
string (template_item_field) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The field name in template_data for which to map corresponding display preferences.

Enum Value Description
ITEMS_QUANTITY

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

ITEMS_DESCRIPTION

The description of the item in the invoice template.

ITEMS_DATE

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

ITEMS_DISCOUNT

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

ITEMS_TAX

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

object (template_display_preference)

The display preference.

{
  • "field_name": "ITEMS_QUANTITY",
  • "display_preference": {
    • "hidden": false
    }
}

template_metadata

The audit metadata. Captures all template actions on create and update.

created_by
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The email address of the account that created the resource.

last_updated_by
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

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_policy_and_agreement_setting

The template policy and agreement setting. Includes the field name and display preference for policy and agreement related fields.

object (template_setting_display_preference)

The template setting display preference.

field_name
string (template_policy_and_agreement_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field name for which to map corresponding display preferences.

Enum Value Description
CANCELLATION_POLICY

Cancellation policy information in the invoice template.

PAYMENT_TERMS

Payment terms information in the invoice template.

RETURN_POLICY

Return policy information in the invoice template.

SERVICE_AGREEMENT

Service agreement information in the invoice template.

TERMS_AND_CONDITIONS

Terms and conditions information in the invoice template.

{
  • "display_preference": {
    • "hidden": true
    },
  • "field_name": "CANCELLATION_POLICY"
}

template_policy_and_agreement_settings_field

The field names for the policy and agreement details in the template.

string (template_policy_and_agreement_settings_field) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The field names for the policy and agreement details in the template.

Enum Value Description
CANCELLATION_POLICY

Cancellation policy information in the invoice template.

PAYMENT_TERMS

Payment terms information in the invoice template.

RETURN_POLICY

Return policy information in the invoice template.

SERVICE_AGREEMENT

Service agreement information in the invoice template.

TERMS_AND_CONDITIONS

Terms and conditions information in the invoice template.

"CANCELLATION_POLICY"

template_setting_display_preference

The template setting display preference.

hidden
boolean

Indicates whether to show or hide this field.

{
  • "hidden": true
}

template_settings

The template settings. Sets a template as the default template or edit template.

Array of objects (template_item_setting) [ 0 .. 2147483647 ] items

The template item headers display preference.

Array of objects (template_subtotal_setting) [ 0 .. 2147483647 ] items

The template subtotal headers display preference.

Array of objects (template_details_setting) [ 0 .. 2147483647 ] items

The template invoice details settings for order, project, and service details.

Array of objects (template_policy_and_agreement_setting) [ 0 .. 2147483647 ] items

The template policy and agreement settings for terms, cancellation, and return policies.

Array of objects (template_additional_setting) [ 1 .. 10 ] items

The template additional fields that define display preferences for references, attachments, and memos.

{
  • "template_item_settings": [
    • {
      • "field_name": "ITEMS_QUANTITY",
      • "display_preference": {
        • "hidden": false
        }
      }
    ],
  • "template_subtotal_settings": [
    • {
      • "field_name": "DISCOUNT",
      • "display_preference": {
        • "hidden": false
        }
      }
    ],
  • "template_details_settings": [
    • {
      • "display_preference": {
        • "hidden": true
        },
      • "field_name": "ORDER_DETAILS"
      }
    ],
  • "template_policy_and_agreement_settings": [
    • {
      • "display_preference": {
        • "hidden": true
        },
      • "field_name": "CANCELLATION_POLICY"
      }
    ],
  • "template_additional_settings": [
    • {
      • "display_preference": {
        • "hidden": true
        },
      • "field_name": "ATTACHMENT"
      }
    ]
}

template_subtotal_field

The field names in the template for discount, shipping, and custom amounts.

string (template_subtotal_field) [ 1 .. 2147483647 ] characters ^[\S\s]*$

The field names in the template for discount, shipping, and custom amounts.

Enum Value Description
DISCOUNT

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

SHIPPING

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

CUSTOM

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

SHIPPING_TAX

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

"DISCOUNT"

template_subtotal_setting

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

field_name
string (template_subtotal_field) [ 1 .. 2147483647 ] characters ^[\S\s]*$

The field name in template_data for which to map corresponding display preferences.

Enum Value Description
DISCOUNT

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

SHIPPING

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

CUSTOM

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

SHIPPING_TAX

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

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)) [ 0 .. 2147483647 ] items

An array of addresses in the user's PayPal profile.

Array of objects (phone_detail) [ 0 .. 2147483647 ] items

An array of phone numbers in the user's PayPal profile.

Array of objects (template) [ 0 .. 2147483647 ] items

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) [ 0 .. 2147483647 ] items

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",
      • "description": "string",
      • "default_template": true,
      • "standard_template": true,
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET",
          • "title": "string",
          • "mediaType": "string",
          • "encType": "application/json",
          • "schema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            },
          • "targetSchema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            }
          }
        ],
      • "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"
              }
            ],
          • "tip_presets": [
            • {
              • "percent": "19.99"
              }
            ],
          • "order_details": "string",
          • "project_details": "string",
          • "service_details": "string",
          • "cancellation_policy": "string",
          • "payment_terms": "string",
          • "return_policy": "string",
          • "service_agreement": "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,
          • "has_conditional_rule": false,
          • "save_item_for_future": true,
          • "discount_mode_preference": "ONE_TIME",
          • "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
              }
            }
          ],
        • "template_details_settings": [
          • {
            • "display_preference": {
              • "hidden": true
              },
            • "field_name": "ORDER_DETAILS"
            }
          ],
        • "template_policy_and_agreement_settings": [
          • {
            • "display_preference": {
              • "hidden": true
              },
            • "field_name": "CANCELLATION_POLICY"
            }
          ],
        • "template_additional_settings": [
          • {
            • "display_preference": {
              • "hidden": true
              },
            • "field_name": "ATTACHMENT"
            }
          ]
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "emails": "string"
}

The status of the feature.

Indicates the status of the feature. If this feature is a paywall feature, it reflects the status of the associated subscription.

string (The status of the feature.) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Indicates the status of the feature. If this feature is a paywall feature, it reflects the status of the associated subscription.

Enum Value Description
ACTIVE

Represents the feature is active.

CANCELLED

Represents the feature is cancelled.

PENDING_CANCELLATION

Represents the feature is in pending cancelled state.

PENDING_ACTIVATION

Represents the feature is in pending activation state.

SUSPENDED

Represents the feature is suspended.

REVOKED

Represents the feature has been revoked.

APPROVED

Represents the feature has been approved.

IN_REVIEW

Represents the feature is currently under review.

NEED_DATA

Represents the feature requires additional data.

DENY

Represents the feature has been denied.

INACTIVE

Represents the feature is inactive.

PENDING

Represents the feature is in a pending state.

"ACTIVE"

The type of the feature.

Indicates the type of the feature.

string (The type of the feature.) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

Indicates the type of the feature.

Enum Value Description
PAID

Represents the feature is a paid feature.

FREE

Represents the feature is a free feature.

"PAID"

Theme

This object represents a merchant pre-defined layout and visual representation that defines the appearance of Invoicing buyer view page for branding a merchant.

layout
string (layout) [ 1 .. 155 ] characters ^[A-Z0-9_]+$

Represent the layout opted by merchant.

Enum Value Description
CLASSIC

Default classic invoice layout.

BRANDED

Customised invoice layout.

primary_color
string (Color hex code) [ 4 .. 7 ] characters ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

Represents the primary color opted by merchant.

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 when the theme is created.

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 when the theme is updated.

{
  • "layout": "CLASSIC",
  • "primary_color": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

time_based_uuid

The time based universally unique identifier (UUID) in Universally Unique IDentifier (UUID) URN Namespace format.

string <ppaas_time_based_uuid_v1> (time_based_uuid) = 36 characters ^[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{8}...

The time based universally unique identifier (UUID) in Universally Unique IDentifier (UUID) URN Namespace format.

"stringstringstringstringstringstring"

tip_preset

Defines a tip option that can be presented to the customer as a percentage of the invoice total. Note: This preset represents a tip configuration where the percentage value is applied during checkout to calculate the tip amount.

percent
string [ 1 .. 20 ] characters ^(([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 tip percentage ranges from 0.00001 to 100.00000 inclusive and supports up to five decimal places.

{
  • "percent": "19.99"
}

transmission_type

Indicates the channel of the notification delivery.

string (transmission_type) [ 1 .. 40 ] characters ^[A-Z0-9_]+$

Indicates the channel of the notification delivery.

Enum Value Description
SMS

Transmission Type is SMS.

EMAIL

Transmission Type is EMAIL.

PUSH

Transmission Type is PUSH.

PAPER

Transmission Type is PAPER.

HTTP

Transmission Type is HTTP.

"SMS"

type

Type of the stored discount. Used to determine wheather its percentage or absolute currency value.

string (type) [ 1 .. 20 ] characters ^[A-Z0-9_]*$

Type of the stored discount. Used to determine wheather its percentage or absolute currency value.

Enum Value Description
PERCENT

Percentage of discount used in invoice item or in an invoice.

AMOUNT

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

"PERCENT"

unit_of_measure

The unit of measure for the invoiced item.

string (unit_of_measure) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unit of measure for the invoiced item.

Enum Value Description
QUANTITY

The unit of measure is quantity. This invoice template is typically used for physical goods.

HOURS

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

AMOUNT

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

"QUANTITY"

uuid

The universally unique identifier (UUID) in Universally Unique IDentifier (UUID) URN Namespace format.

string <ppaas_uuid_v3> (uuid) = 36 characters ^[0-9a-zA-Z]{8}-[0-9a-zA-Z]{4}-[0-9a-zA-Z]{4}...

The universally unique identifier (UUID) in Universally Unique IDentifier (UUID) URN Namespace format.

"stringstringstringstringstringstring"