On this page
No Headings
Last updated: June 12, 2026
Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.
Updates or deletes a billing agreement.
| Field | Description |
|---|---|
METHOD | (Required) Must be BillAgreementUpdate. |
REFERENCEID | (Required) An ID, such as a billing agreement ID or a reference transaction ID that is associated with a billing agreement. |
BILLINGAGREEMENTSTATUS | (Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the value Canceled. Note: If you do not pass the value Canceled, BAUpdate returns the buyer's latest billing address. |
BILLINGAGREEMENTDESCRIPTION | (Optional) Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. PayPal recommends that the description contain a brief summary of the billing agreement terms and conditions. For example, buyer will be billed at "9.99 per month for 2 years." Character length and limitations: 127 single-byte alphanumeric characters |
BILLINGAGREEMENTCUSTOM | (Optional) Custom annotation field for your own use. Note: For recurring payments, this field is ignored. |
| Field | Description |
|---|---|
BILLINGAGREEMENTID | Identification number of the billing agreement. When the buyer approves the billing agreement, it remains valid until canceled by the buyer. Note: For reference transactions, you can pass a billing agreement ID in the ReferenceID request field. Also, a billing agreement ID is returned in the transaction response when the transaction references a billing agreement. Character length and limitations: 19 single-byte alphanumeric characters |
BILLINGAGREEMENTDESCRIPTION | Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. Character length and limitations: 127 single-byte alphanumeric characters |
BILLINGAGREEMENTCUSTOM | Custom annotation field for your own use. Character length and limitations: 256 single-byte alphanumeric characters |
BILLINGAGREEMENTSTATUS | (Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the value Canceled. Note: If you do not pass the value Canceled, BAUpdate returns the buyer's latest billing address. |
BILLINGAGREEMENTMAX | Maximum amount for this billing agreement. Note: This field only has a value if the buyer signed up for PayPal using Preapproved Payments; it is included for backwards compatibility with deprecated systems. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
BILLINGADDRESS | Customer's billing address. If the customer has stored a credit card in his/her account then the billing address of the credit card is returned; otherwise the customer's primary address is returned. |
| Field | Description |
|---|---|
EMAIL | Email address of buyer. Character length and limitations: 127 single-byte characters |
PAYERID | Unique PayPal Customer Account identification number. Character length and limitations: 17 single-byte alphanumeric characters |
PAYERSTATUS | Status of buyer. It is one of the following values:
|
COUNTRYCODE | Buyer's country of residence in the form of ISO standard 3166 2-character country codes. Character length and limitations: 2 single-byte characters |
PAYERBUSINESS | Buyer's business name. Character length and limitations: 127 single-byte characters |
| Field | Description |
|---|---|
SALUTATION | Buyer's salutation. Character length and limitations: 20 single-byte characters |
FIRSTNAME | Buyer's first name. Character length and limitations: 64 single-byte characters |
MIDDLENAME | Buyer's middle name. Character length and limitations: 64 single-byte characters |
LASTNAME | Buyer's last name. Character length and limitations: 64 single-byte characters |
SUFFIX | Buyer's suffix. Character length and limitations: 12 single-byte characters |
| Field | Description |
|---|---|
BILLINGNAME | Billing name associated with this billing address. Character length and limitations: 32 single-byte characters |
STREET | First billing street address. Character length and limitations: 100 single-byte characters |
STREET2 | Second billing street address. Character length and limitations: 100 single-byte characters |
CITY | Name of billing city. Character length and limitations: 40 single-byte characters |
STATE | Billing state or province. Required for U.S. addresses only. Character length and limitations: 40 single-byte characters |
ZIP | U.S. billing ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters |
COUNTRYCODE | Billing country code. Character length and limitations: 2 single-byte characters |
Information about the merchant or the owner of the billing agreement.
| Field | Description |
|---|---|
PAYEEEMAIL | Email address of the merchant or owner of the billing agreement. Character length and limitations: 127 single-byte characters |
PAYEEID | Unique merchant account identification number. Character length and limitations: 17 single-byte alphanumeric characters |