BMUpdateButton API Operation (NVP)

Use the BMUpdateButton API operation to modify a PayPal Payments Standard button that is hosted on PayPal. This operation replaces all fields in the specified button; therefore, you must specify a value fore each field you want to include for the button, whether or not it changed.

BMUpdateButton Request

The hosted button ID identifies the button you want to modify. The remaining request fields specify the characteristics of your button.

BMUpdateButton Request Fields

Field

Description

METHOD

(Required) BMUpdateButton

HOSTEDBUTTONID

(Required) The ID of the hosted button you want to modify.

BUTTONTYPE

(Required) The kind of button you want to update. It is one of the following values:


  • BUYNOW - Buy Now button

  • CART - Add to Cart button

  • GIFTCERTIFICATE - Gift Certificate button

  • SUBSCRIBE - Subscribe button

  • DONATE - Donate button

  • UNSUBSCRIBE - Unsubscribe button

  • VIEWCART - View Cart button

  • PAYMENTPLAN - Installment Plan button; since version 63.0

  • AUTOBILLING - Automatic Billing button; since version 63.0

Note: You cannot change the kind of button after the button has been created.

BUTTONCODE

(Optional) The kind of button code to create. It is one of the following values:


  • HOSTED - A secure button stored on PayPal; default for all buttons except View Cart and Unsubscribe

  • ENCRYPTED - An encrypted button, not stored on PayPal; default for View Cart button

  • CLEARTEXT - An unencrypted button, not stored on PayPal; default for Unsubscribe button

    Note: You cannot change the kind of button code after after the button has been created.

BUTTONSUBTYPE

(Optional) The use of button you want to create. It is one of the following values:


  • PRODUCTS - button is used to purchase products; default for Buy Now and Add to Cart buttons

  • SERVICES - button is used to purchase services

Note: You cannot change the button usage after after the button has been created.

L_BUTTONVARn

(Optional) HTML standard button variables

It is a list of variables, in which n is a digit between 0 and 999, inclusive; do not include leading zeros.

Character length and limitations: 63 single-byte alphanumeric characters each

L_TEXTBOXn

xs:string

(Optional) Text description for a menu item

It is a list of variables, in which n is a digit between 0 and 1, inclusive.

BUTTONIMAGE

(Optional) The kind of button image. It is one of the following values:


  • REG - regular; default

  • SML - small

  • CC - small button image with credit card logos; not applicable for Unsubscribe or View Cart buttons

    Note: Specify either the kind of button image or the URL.

BUTTONIMAGEURL

xs:string

(Optional) The button's URL

Note: Specify either the kind of button image or the URL.

BUYNOWTEXT

(Optional) The button text for a Buy Now button. It is one of the following values:


  • BUYNOW - button text is Buy Now; default

  • PAYNOW - button text is Pay Now

SUBSCRIBETEXT

(Optional) The button text for a Subscribe button. It is one of the following values:


  • BUYNOW - button text is Buy Now

  • SUBSCRIBE - button text is Subscribe; default

BUTTONCOUNTRY

(Optional) The country in which the transaction occurs. By default, it is the merchant's country of registration with PayPal.

BUTTONLANGUAGE

xs:string

(Optional) The language in which to display the button text. It must be compatible with the country code.

Character length and limitations: 2 single-byte alphanumeric characters

Option Details Fields

Field

Description

OPTIONnNAME

(Optional) The menu name

It is one or more variables, in which n is a digit between 0 and 4, inclusive, for hosted buttons; otherwise, it is a digit between 0 and 9, inclusive.

Option Selection Details Fields

L_OPTIONnSELECTx

(Optional) The menu item's name

It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 9, inclusive

L_OPTION0PRICEx

(Optional) The price associated with the first menu item

It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 9, inclusive

Note: If you specify a price, you cannot set a button variable to amount.

OPTIONnTYPE

(Optional) The installment option type for an OPTIONnNAME, which is one of the following values:


  • FULL - Payment in full

  • VARIABLE - Variable installments

  • EMI - Equal installments

Note: Only available for Installment Plan buttons.

Installment Details

L_OPTIONnBILLINGPERIODx

(Optional) The installment cycle unit, which is one of the following values:


  • NoBillingPeriodType - None (default)

  • Day

  • Week

  • SemiMonth

  • Month

  • Year

It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnBILLINGPFREQUENCYx

(Optional) The installment cycle frequency in units, e.g. if the billing frequency is 2 and the billing period is Month, the billing cycle is every 2 months. The default billing frequency is 1.

It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnTOTALBILLINGCYCLESx

(Optional) The total number of billing cycles, regardless of the duration of a cycle; 1 is the default

It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnAMOUNTx

(Optional) The base amount to bill for the cycle.

It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnSHIPPINGAMOUNTx

(Optional) The shipping amount to bill for the cycle, in addition to the base amount.

It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnTAXAMOUNTx

(Optional) The tax amount to bill for the cycle, in addition to the base amount.

It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

Button Language Options

The button language must be compatible with the country identified by the country code.

Country

Button Language Options

All countries not identified below


  • en - English; default

Austria


  • de - German; default

  • en - English

Belgium


  • en - English; default

  • nl - Dutch

  • fr - French

Canada


  • en - English; default

  • fr - French

China (worldwide)


  • en - English; default

  • zh - Chinese

France


  • fr - French; default

  • en - English

Germany


  • de - German; default

  • en - English

Hong Kong


  • zh - Chinese; default

  • en - English

Italy


  • it - Italian; default

  • en - English

Japan


  • ja - Japanese; default

  • en - English

Mexico


  • es - Spanish; default

  • en - English

Netherlands


  • nl - Dutch; default

  • en - English

Poland


  • pl - Polish; default

  • en - English

Spain


  • es - Spanish; default

  • en - English

Switzerland


  • de - German; default

  • fr - French

  • en - English

United States


  • en - English; default

  • fr - French

  • es - Spanish

  • zh - Chinese

BMUpdateButton Response

The response contains the hosted button ID, code for HTML in a website, and code for a link in email.

BMUpdateButton Response Fields

Field

Description

WEBSITECODE

HTML code for web pages

EMAILLINK

Code for email links and links in other documents that support external links

HOSTEDBUTTONID

ID of a PayPal hosted button

BMUpdateButton Errors

Error Code

Short Message

Long Message

Correcting This Error...

10001 Internal Error Internal Error
11923 Invalid Argument The button image value specified is invalid.
11924 Invalid Argument The button image URL specified is invalid.
11925 Invalid Argument The button type specified is invalid.
11926 Invalid Data One of the parameters specified using ButtonVar is invalid.
11927 Invalid Argument The buy now button text specified is invalid.
11928 Invalid Argument The email or merchant ID specified is invalid.
11929 Invalid Data A cart button must have an item name and amount specified.
11930 Invalid Data A gift certificate button must have a valid shopping URL specified.
11931 Invalid Argument The subscription button text specified is invalid.
11932 Invalid Data You must specify a corresponding number of entries for option names and selections.
11933 Invalid Data You cannot skip index numbers for option selections. Option selections must be specified sequentially.
11934 Invalid Data You must specify the same number of entries for option prices and selections.
11936 Invalid Data You cannot specify both an item price and prices for individual selections within an option.
11937 Invalid Argument A text box name specified is invalid. Text box names must not exceed 64 characters.
11938 Invalid Argument The button code value specified is invalid.
11940 Invalid Argument An option name specified is invalid. Option names must not exceed 64 characters.
11941 Invalid Argument An option selection value specified is invalid. Option selection values must not exceed 64 characters.
11942 Invalid Argument An option price value specified is invalid. Make sure any punctuation marks are in the correct places.
11943 Invalid Argument The button country value specified is invalid.
11945 Invalid Data The button country and language code combination specified is invalid.
11947 Invalid Argument The tax rate specified is invalid. Make sure any punctuation marks are in the correct places and value specified is in the range 0.0 to 100.
11948 Invalid Argument The amount specified is invalid. Make sure any punctuation marks are in the correct places.

12210

Invalid Argument

The currency code value specified is invalid.

13117

Invalid Argument

Subtotal amount is not valid.

13118

Invalid Argument

Tax amount is not valid.

13119

Invalid Argument

Handling amount is not valid.

13120

Invalid Argument

Shipping amount is not valid.