UpdateRecurringPaymentsProfile API Operation (SOAP)

ProfileID

xs:string

(Required) Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response.

Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatibility with previous versions of the PayPal API.

Note

xs:string

(Optional) The reason for the update to the recurring payments profile. This message is included in the email notification to the buyer for the recurring payments profile update. This note can also be seen by both you and the buyer on the Status History page of the PayPal account.

Description

xs:string

(Optional) Description of the recurring payment.

Character length and limitations: 127 single-byte alphanumeric characters

SubscriberName

xs:string

(Optional) Full name of the person receiving the product or service paid for by the recurring payment. If not present, the name in the buyer's PayPal account is used.

Character length and limitations: 32 double-byte characters

SubscriberShipping Address

ns:AddressType

(Optional) The subscriber's shipping address associated with this profile, if applicable. If you do not specify it, the ship-to address from buyer's PayPal account is used.

Note: Shipping Address is optional, but if you update any of the address fields, you must enter all of them. For example, if you want to update the subscriber's street address, you must specify all of the fields listed in ShipTo: AddressType, not just the field for the street address.

ProfileReference

xs:string

(Optional) The merchant's own unique reference or invoice number.

Character length and limitations: 127 single-byte alphanumeric characters

AdditionalBilling Cycles

xs:int

(Optional) The number of additional billing cycles to add to this profile.

Amount

cc:BasicAmountType

(Optional) Billing amount for each cycle in the subscription period, not including shipping and tax amounts.

Note: For recurring payments with Express Checkout, the payment amount can be increased by no more than 20% every 180 days (starting when the profile is created).

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

ShippingAmount

cc:BasicAmountType

(Optional) Shipping amount for each billing cycle during the regular payment period.

Note: All amounts in the request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TaxAmount

cc:BasicAmountType

(Optional) Tax amount for each billing cycle during the regular payment period.

Note: All amounts in the request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

OutstandingBalance

cc:BasicAmountType

(Optional) The current past due or outstanding amount for this profile. You can only decrease the outstanding amount. It cannot be increased.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

AutoBillOutstanding Amount

ns:AutoBillType

(Optional) This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. Value is:

• NoAutoBill — PayPal does not automatically bill the outstanding balance.

• AddToNextBilling — PayPal automatically bills the outstanding balance

MaxFailedPayments

xs:int

(Optional) The number of failed payments allowed before the profile is automatically suspended. The specified value cannot be less than the current number of failed payments for this profile.

Character length and limitations: Number string representing an integer

BillingStartDate

xs:dateTime

(Optional) The date when billing for this profile begins.

Note: The profile may take up to 24 hours for activation.

Character length and limitations: Must be a valid date, in UTC/GMT format; for example, 2013-08-24T05:38:48Z. No wildcards are allowed.

TrialPeriod

ns:BillingPeriodDetailsType

(Optional) The trial period for this schedule.

PaymentPeriod

ns:BillingPeriodDetailsType

(Optional) The regular payment period for this schedule.

CreditCard

ns:CreditCardDetailsType

(Optional) Credit card information for this profile, if applicable. Credit card billing address is optional, but if you update any of the address fields, you must enter all of them. For example, if you want to update the street address, you must specify all of the address fields listed in CreditCardDetailsType, not just the field for the street address.

Note: Only enter credit card details for recurring payments with direct payments.

Name

xs:string

Person's name associated with this shipping address. It is required if using a shipping address.

Character length and limitations: 32 double-byte characters

Street1

xs:string

First street address. It is required if using a shipping address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

Name of city. It is required if using a shipping address.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

State or province.
Required for transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. See the list of PayPal state codes.

Character length and limitations: 40 single-byte characters

PostalCode

xs:string

U.S. ZIP code or other country-specific postal code. It is required if using a U.S. shipping address; may be required for other countries.

Character length and limitations: 20 single-byte characters

Country

ebl:CountryCodeType

Country code. It is required if using a shipping address.

Character length and limitations: 2 single-byte characters

Phone

xs:string

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

PaymentPeriod.TotalBillingCycles

xs:int

(Optional) Number of billing cycles for payment period.

• For the regular payment period, if no value is specified or the value is 0, the regular payment period continues until the profile is canceled or deactivated.

• For the regular payment period, if the value is greater than 0, the regular payment period will expire after the trial period is finished and continue at the billing frequency for TotalBillingCycles cycles.

PaymentPeriod.Amount

cc:BasicAmountType

(Required) Billing amount for each billing cycle during this payment period. This amount does not include shipping and tax amounts.

Note: All amounts in the CreateRecurringPaymentsProfile request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TrialPeriod.TotalBillingCycles

xs:int

(Optional) Number of billing cycles for trial payment period.

TrialPeriod.Amount

cc:BasicAmountType

Billing amount for each billing cycle during this payment period; required if you specify an optional trial period. This amount does not include shipping and tax amounts.

Note: All amounts in the CreateRecurringPaymentsProfile request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

ShippingAmount

cc:BasicAmountType

(Optional) Shipping amount for each billing cycle during this payment period.

Note: All amounts in the request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TaxAmount

cc:BasicAmountType

(Optional) Tax amount for each billing cycle during this payment period.

Note: All amounts in the request must have the same currency.

Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

CreditCardType

ebl:CreditCardType

(Optional) Type of credit card. For UK, only Maestro, Mastercard, Discover, and Visa are allowable. For Canada, only Mastercard and Visa are allowable and Interac debit cards are not supported. Value is:

• Visa
• Mastercard
• Discover
• Amex
• JCB
• Maestro: See note.

Note: If the credit card type is Maestro, you must set currencyId to GBP. In addition, you must specify either StartMonth and StartYear or IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters

CreditCardNumber

xs:string

(Required) Credit card number.

Character length and limitations: Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type.

ExpMonth

xs:int

(Required) Credit card expiration month.

Character length and limitations: 2 single-byte numeric characters, including leading zero

ExpYear

xs:int

(Required) Credit card expiration year.

Character length and limitations: 4 single-byte numeric characters

CVV2

xs:string

Card Verification Value, version 2. Your Merchant Account settings determine whether this field is required. To comply with credit card processing regulations, you must not store this value after a transaction has been completed.

Character length and limitations: For Visa, Mastercard, and Discover, the value is exactly 3 digits. For American Express, the value is exactly 4 digits.

CardOwner

ns:PayerInfoType

(Required) Details about the owner of the credit card.

StartMonth

xs:int

(Optional) Month that Maestro card was issued.

Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int

(Optional) Year that Maestro card was issued.

Character length and limitations: 4 digits

IssueNumber

xs:string

(Optional) Issue number of Maestro card.

Character length and limitations: 2 numeric digits maximum

Payer

ns:EmailAddressType

(Optional) Email address of buyer.

Character length and limitations: 127 single-byte characters

FirstName

ns:PersonNameType

(Required) Buyer's first name.

Character length and limitations: 64 double-byte characters

LastName

ns:PersonNameType

(Required) Buyer's last name.

Character length and limitations: 64 double-byte characters

Address

ns:AddressType

(Required) Buyer's billing address information.

Street1

xs:string

(Required) First street address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

(Required) Name of city.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

(Required) State or province.

Character length and limitations: 40 single-byte characters

Country

ebl:CountryCodeType

(Required) Country code.

Character length and limitations: 2 single-byte characters

PostalCode

xs:string

(Required) U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

Phone

xs:string

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

ProfileID

xs:string

Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. An error is returned if the profile specified in the BillOutstandingAmount request has a status of canceled or expired.