Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
This document describes the Button Manager API for SOAP.
Intended Audience
This document is intended for merchants and developers implementing Website Payment
Standard buttons using an API.
Revision History
Revision history for Website Payments Standard Button Manager API (SOAP).
TABLE P.1 Revision History
DateDescription
06/03/09Added HTML Variable appendix and updated for version 57.0.
03/31/09Initial draft.
Button Manager SOAP APIJune, 20095
Revision History
6June, 2009Button Manager SOAP API
1
Website Payments Standard
Button Manager API Overview
The Website Payments Standard Button Manager API allows you to programatically create,
manage, edit, and delete Website Payment Standard buttons, which are the same kind of
buttons that you can create from the PayPal Profile. Hosted buttons created by this API reside
on PayPal and can use all features, including inventory management; however, you can use
this API to create code for non-hosted Website Payment Standard buttons as well.
z Button Manager Introduction
z Generated Button Code
z Button Hosting
z Hosted Button Manipulation
z Inventory Management Using Hosted Buttons
z Button Manager API Summary
z Granting Third-Party Permission for APIs
Button Manager Introduction
You should consider creating and managing your buttons with the Button Manager API when
you are creating more than just a few Website Payment Standard buttons or when you manage
buttons for others; for example, if you provide a shopping cart for merchants.
The Button Manager API enables you to manage Website Payment Standard buttons
programatically in the same way that you can manage them on PayPal from the My Saved
Buttons page of your Profile.
NOTE: You can access your My Saved Buttons page on PayPal by choosing My Saved
Buttons from the Profile’s Selling Preferences column. If no buttons have been
created, the menu item is Create New Button.
You can use the API to create the following types of Website Payment Standard buttons:
z Buy Now
z Add to Cart and View Cart
z Donate
z Buy Gift Certificate
z Subscribe and Unsubscribe
The following buttons are some of those that you can create using the Button Manager API:
Button Manager SOAP APIJune, 20097
Website Payments Standard Button Manager API Overview
Generated Button Code
Generated Button Code
When you create a button, PayPal responds by providing code that you can paste into your
web page or document.
PayPal generates code that you can use for the button, which includes
z HTML code for including the button in web pages
z URL link code for adding buttons to email and documents that support links
NOTE: Not all buttons that can be created are available to merchants in every country; for
example, German merchants cannot use Subscribe buttons even though they can be
created through the API. If you can create the button for the specified country using
Create PayPal payment button on PayPal, your merchant will be able to use the button.
The following example shows the PayPal code to display a hosted Add to Cart button for a
wireless mouse:
8June, 2009Button Manager SOAP API
Website Payments Standard Button Manager API Overview
For a link, PayPal does not generate code for options.
Button Hosting
Buttons that you can view on the My Saved Buttons page of your PayPal profile are called
hosted buttons because they reside on PayPal. The API can create three kinds of buttons:
hosted, encrypted, and clear text.
Button Manager SOAP APIJune, 20099
Website Payments Standard Button Manager API Overview
Hosted Button Manipulation
z Hosted buttons are stored on PayPal. The parameters associated with this kind of button are
secure.
Hosted buttons provide the greatest flexibility because you can instruct PayPal to change
them dynamically and PayPal maintains information about their state, such as the inventory
level associated with the button.
z Encrypted buttons are not stored on PayPal. The parameters associated with this kind of
button are encrypted.
Encrypted buttons are similar to hosted buttons with regards to secure operation; however,
you must update the web pages that use an encrypted button each time the button or its
associated information changes. You should only use an encrypted button if a hosted button
cannot be used.
z Clear text buttons are not stored on PayPal. The parameters associated with this kind of
button are not encrypted.
Clear text buttons are not hosted and are not encrypted. They can be used dynamically
because you can change the value of a parameter “on the fly.” However, if you use them,
recognize the risk that sensitive information can be altered or stolen.
Hosted Button Manipulation
When you create a hosted button, the response includes an ID that allows you to manipulate
the button using the Button Manager API.
Specifically, you can
z Get a list of all hosted buttons defined, which allows you to obtain a list of all your buttons
for further programatic manipulation
z Get details about a hosted button, which allows you to identify the parameters and values
associated with a button
z Update a hosted button, which allows you to change individual parameters, such as price,
in a hosted button
z Manage hosted button status; currently, you can only delete a button
z Get and set inventory information associated with the button
Inventory Management Using Hosted Buttons
If you use hosted buttons, you can set inventory values for the item associated with the button
and get inventory values for the item. You can also track inventory on options within an item,
such as color, size, and so on.
If you enable inventory management for a button, PayPal tracks inventory for you and also lets
your buyer know whether the item is sold out. You can specify inventory tracking on an itemby-item basis and also by option, such as color or size, within the item.
10June, 2009Button Manager SOAP API
Website Payments Standard Button Manager API Overview
You are alerted by e-mail if the inventory on hand falls below the threshold you specify. If an
item is sold out, you can specify whether or not to accept a payment anyway. Optionally, you
can specify a URL to which your buyer’s browser is redirected if the item is sold out.
Additionally, you can enable profit and loss tracking for an item or option associated with a
button. If you enable this feature, you must provide the cost of the item or option. PayPal then
calculates your gross profit, which is the selling price of the item less the specified cost.
Button Manager API Summary
The Button Manager API is available for both NVP and SOAP.
API OperationDescription
BMCreateButtonCreate button code
BMUpdateButtonUpdate a hosted button
BMManageButtonStatusDelete a button
Button Manager API Summary
BMGetButtonDetailsObtain information about the parameters associated with a button
BMButtonSearchObtain a list of all buttons
BMGetInventoryObtain the inventory levels associated with a button
BMSetInventorySpecify the inventory levels associated with a button
Granting Third-Party Permission for APIs
If you allow a shopping cart or another party to create buttons on your behalf, you must grant
the party permission to execute Button Manager API operations for you.
To grant third-party permissions
1. Log in to your PayPal account.
2. Select My Account Profile.
3. Click “API Access” from the Profile Summary.
4. Click “Grant API Permission.”
5. Click to “Configure a custom API authorization.”
6. Enter your Partner API Username, as specified by your shopping cart or third party.
7. Click to check each Button Manager API to which you want to provide access:
Button Manager SOAP APIJune, 200911
Website Payments Standard Button Manager API Overview
Granting Third-Party Permission for APIs
8. Click Submit.
12June, 2009Button Manager SOAP API
Using the Button Manager API
2
These examples show basic Button Manager API capabilities. The examples show how to
create buttons and set inventory levels.
z Specifying HTML Variables
z Creating a Button Using SOAP
z Tracking Inventory for a Button Using SOAP
Specifying HTML Variables
When you create or update a button using the Button Manager API, you must specify the same
HTML variables that you specify when creating any Website Payments Standard button.
Although you can use the ButtonVar field to specify any HTML variables, some variables
are commonly used in specific ways.
The following table provides additional information about some of these variables:
HTML VariableNotes
item_nameName or description of item. Must be specified for Add to Cart buttons.
Character length and limitations: 127 single-byte alphanumeric characters.
amountThe price or amount of the item. Required for Add to Cart buttons. May not
be used when a dropdown with price (L_OPTION0PRICE
Limitations: Value must be a positive number. No currency symbol. Must have
two decimal places, decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
a3Price of subscription. Must be specified for Subscribe buttons. Value must be
a positive number. No currency symbol. Must have two decimal places,
decimal separator must be a period (.), and the optional thousands separator
must be a comma (,).
p3Regular billing cycle. Must be specified for Subscribe buttons. Limitations:
Must be a positive integer greater than 0 and less than or equal to 30
t3Regular billing cycle units. Must be specified for Subscribe buttons.
shopping_urlURL where recipients can shop and redeem gift certificates. Required for Gift
Certificate buttons. Character length and limitations: 255 single-byte
alphanumeric characters
n) is defined.
Button Manager SOAP APIJune, 200913
Using the Button Manager API
Creating a Button Using SOAP
HTML VariableNotes
no_noteMust be specified for Subscribe buttons. Enables a subscriber to not be
prompted to include a note with the subscription, a function which PayPal
subscriptions does not support. This variable must be included, and the value
must be set to 1.
businessSecure Merchant ID or Email Address. When omitted, defaults to the secure
merchant ID of the merchant. If an email address is specified then it the
following requirements apply:
z A merchant or 3rd Party calling the API directly may specify an
unregistered email and create an unencrypted button only.
z A 3rd Party calling the API on behalf of a registered merchant must specify
an email address associated with the merchant account.
Character length and limitations: 127 single-byte characters.
item_numberItem number or ID. Character length and limitations: 127 single-byte
alphanumeric characters.
lcIf specified, it overrides the value set in the ButtonCode field.
For a complete list of HTML variables and complete information, see HTML Variables for
Website Payments Standard.
Creating a Button Using SOAP
The example sets up a SOAP request message to create a button.
The Button Manager API enables you to programatically create, edit, and delete Website
Payment Standard buttons hosted on PayPal and track product inventory associated with these
buttons. You can also create non-hosted buttons with the Button Manager API; however,
button maintenance and inventory management are only supported for hosted buttons.
z BMCreateButton API Operation
z BMUpdateButton API Operation
z BMButtonSearch API Operation
z BMCreateButton API Operation
z BMManageButtonStatus API Operation
z BMSetInventory API Operation
z BMGetInventory API Operation
BMCreateButton API Operation
Use the BMCreateButton API operation to create a Website Payments Standard button. You
an create either a button that is hosted on PayPal or a non-hosted button.
z BMCreateButton Request
z BMCreateButton Response
z BMCreateButton Errors
BMCreateButton Request
The request fields specify the characteristics of your button, which include associated menu
items related to the button. You can specify up five menu items, each of which can include up
to 10 possible selections.
Button Manager SOAP APIJune, 200919
Button Manager API Reference
BMCreateButton API Operation
BMCreateButton Request Fields
FieldDescription
ButtonCodeebl:ButtonCodeType
(Optional) The kind of button code to create. It is one of the following values:
z HOSTED - A secure button stored on PayPal; default for all buttons except
View Cart and Unsubscribe
z ENCRYPTED - An encrypted button, not stored on PayPal; default for View
Cart button
z CLEARTEXT - An unencrypted button, not stored on PayPal; default for
Unsubscribe button
ButtonTypeebl:ButtonTypeType
(Required) The kind of button you want to create. It is one of the following
values:
z BUYNOW - Buy Now button
z CART - Add to Cart button
z GIFTCERTIFICATE - Gift Certificate button
z SUBSCRIBE - Subscribe button
z DONATE - Donate button
z UNSUBSCRIBE - Unsubscribe button
z VIEWCART - View Cart button
ButtonSubTypeebl:ButtonSubTypeType
(Optional) The use of button you want to create. It is one of the following
values:
z PRODUCTS - button is used to purchase products; default for Buy Now and
Add to Cart buttons
z SERVICES - button is used to purchase services
20June, 2009Button Manager SOAP API
FieldDescription
ButtonVarxs:string
(Optional) HTML standard button variables, which are described in HTML
Variables for Website Payments Standard
It is a list of variables, in which
not include leading zeros.
Character length and limitations: 63 single-byte alphanumeric characters each
OptionDetailsns:OptionDetailsType
(Optional) Menu items
TextBoxxs:string
(Optional) Text description for a menu item
It is a list of variables, in which
ButtonImageebl:ButtonImageType
(Optional) The kind of button image. It is one of the following values:
z REG - regular; default unless a button URL is specified
z SML - small
z CC - small button image with credit card logos; not applicable for
Unsubscribe or View Cart buttons
Button Manager API Reference
BMCreateButton API Operation
n is a digit between 0 and 999, inclusive; do
n is a digit between 0 and 1, inclusive.
NOTE: Specify either the kind of button image or the URL.
ButtonImageURLxs:string
(Optional) The button’s URL
NOTE: Specify either the kind of button image or the URL.
BuyNowTextebl:BuyNowTextType
(Optional) The button text for a Buy Now button. It is one of the following
values:
z BUYNOW - button text is Buy Now; default
z PAYNOW - button text is Pay Now
SubscribeTextebl:SubscribeTextType
(Optional) The button text for a Subscribe button. It is one of the following
values:
z BUYNOW - button text is Buy Now
z SUBSCRIBE - button text is Subscribe; default
ButtonCountryebl:CountryCodeType
(Optional) The country in which the transaction occurs. See Country Codes
for a list of country codes. By default, it is the merchant’s country of
registration with PayPal.
ButtonLanguagexs: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
(Optional) The price associated with the first menu item
NOTE: If you specify a price, you cannot set a button variable to amount.
Button Language Options
The button language must be compatible with the country identified by the country code.
CountryButton Language Options
All countries not identified below
Austria
Belgium
Canada
China (worldwide)
France
Germany
Hong Kong
z en - English; default
z de - German; default
z en - English
z en - English; default
z nl - Dutch
z fr - French
z en - English; default
z fr - French
z en - English; default
z zh - Chinese
z fr - French; default
z en - English
z de - German; default
z en - English
z zh - Chinese; default
z en - English
Italy
z it - Italian; default
z en - English
22June, 2009Button Manager SOAP API
CountryButton Language Options
Button Manager API Reference
BMCreateButton API Operation
Japan
Mexico
Netherlands
Poland
Spain
Switzerland
United States
z ja - Japanese; default
z en - English
z es - Spanish; default
z en - English
z nl - Dutch; default
z en - English
z pl - Polish; default
z en - English
z es - Spanish; default
z en - English
z de - German; default
z fr - French
z en - English
z en - English; default
z fr - French
z es - Spanish
z zh - Chinese
BMCreateButton Response
The response contains an ID if the button is hosted on PayPal, and code for HTML in a
website and for a link in email.
BMCreateButton Response Fields
FieldDescription
Websitexs:string
HTML code for web pages
Button Manager SOAP APIJune, 200923
Button Manager API Reference
BMCreateButton API Operation
FieldDescription
Emailxs:string
Code for email links and links in other documents that support external links
HostedButtonIDxs:string
ID of a PayPal-hosted button
BMCreateButton Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11923Invalid ArgumentThe button image value specified is
invalid.
11924Invalid ArgumentThe button image URL specified is
invalid.
11925Invalid ArgumentThe button type specified is invalid.
11926Invalid DataOne of the parameters specified using
ButtonVar is invalid.
11927Invalid ArgumentThe buy now button text specified is
invalid.
11928Invalid ArgumentThe email or merchant ID specified is
invalid.
11929Invalid DataA cart button must have an item name and
amount specified.
11930Invalid DataA gift certificate button must have a valid
shopping URL specified.
11931Invalid ArgumentThe subscription button text specified is
invalid.
11932Invalid DataYou must specify a corresponding number
of entries for option names and selections.
11933Invalid DataYou cannot skip index numbers for option
selections. Option selections must be
specified sequentially.
11934Invalid DataYou must specify the same number of
entries for option prices and selections.
11936Invalid DataYou cannot specify both an item price and
prices for individual selections within an
option.
24June, 2009Button Manager SOAP API
Button Manager API Reference
BMUpdateButton API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11937Invalid ArgumentA text box name specified is invalid. Text
box names must not exceed 64 characters.
11938Invalid ArgumentThe button code value specified is invalid.
11940Invalid ArgumentAn option name specified is invalid.
Option names must not exceed 64
characters.
11941Invalid ArgumentAn option selection value specified is
invalid. Option selection values must not
exceed 64 characters.
11942Invalid ArgumentAn option price value specified is invalid.
Make sure any punctuation marks are in
the correct places.
11943Invalid ArgumentThe button country value specified is
invalid.
11945Invalid DataThe button country and language code
combination specified is invalid.
11947Invalid ArgumentThe 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.
11948Invalid ArgumentThe amount specified is invalid. Make
sure any punctuation marks are in the
correct places.
BMUpdateButton API Operation
Use the BMUpdateButton API operation to modify a Website 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.
z BMUpdateButton Request
z BMUpdateButton Response
z BMUpdateButton Errors
BMUpdateButton Request
The hosted button ID identifies the button you want to modify. The remaining request fields
specify the characteristics of your button.
Button Manager SOAP APIJune, 200925
Button Manager API Reference
BMUpdateButton API Operation
BMUpdateButton Request Fields
FieldDescription
HostedButtonIDxs:string
(Required) The ID of the hosted button you want to modify.
ButtonTypeebl:ButtonTypeType
(Required) The kind of button you want to update. It is one of the following
values:
z BUYNOW - Buy Now button
z CART - Add to Cart button
z GIFTCERTIFICATE - Gift Certificate button
z SUBSCRIBE - Subscribe button
z DONATE - Donate button
z UNSUBSCRIBE - Unsubscribe button
z VIEWCART - View Cart button
NOTE: You cannot change the kind of button after the button has been
created.
ButtonCodeebl:ButtonCodeType
(Optional) The kind of button code to create. It is one of the following values:
z HOSTED - A secure button stored on PayPal; default for all buttons except
View Cart and Unsubscribe
z ENCRYPTED - An encrypted button, not stored on PayPal; default for View
Cart button
z 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.
26June, 2009Button Manager SOAP API
FieldDescription
ButtonSubTypeebl:ButtonSubTypeType
(Optional) The use of button you want to create. It is one of the following
values:
z PRODUCTS - button is used to purchase products; default for Buy Now and
Add to Cart buttons
z SERVICES - button is used to purchase services
NOTE: You cannot change the button usage after after the button has been
created.
ButtonVarxs:string
(Optional) HTML standard button variables, which are described in HTML
Variables for Website Payments Standard
It is a list of variables, in which
not include leading zeros.
Character length and limitations: 63 single-byte alphanumeric characters each
OptionDetailsns:OptionDetailsType
(Optional) Menu items
Button Manager API Reference
BMUpdateButton API Operation
n is a digit between 0 and 999, inclusive; do
TextBoxxs:string
(Optional) Text description for a menu item
It is a list of variables, in which
ButtonImageebl:ButtonImageType
(Optional) The kind of button image. It is one of the following values:
z REG - regular; default
z SML - small
z 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.
ButtonImageURLxs:string
(Optional) The button’s URL
NOTE: Specify either the kind of button image or the URL.
BuyNowTextebl:BuyNowTextType
(Optional) The button text for a Buy Now button. It is one of the following
values:
z BUYNOW - button text is Buy Now; default
z PAYNOW - button text is Pay Now
SubscribeTextebl:SubscribeTextType
(Optional) The button text for a Subscribe button. It is one of the following
values:
z BUYNOW - button text is Buy Now
z SUBSCRIBE - button text is Subscribe; default
n is a digit between 0 and 1, inclusive.
Button Manager SOAP APIJune, 200927
Button Manager API Reference
BMUpdateButton API Operation
FieldDescription
ButtonCountryebl:CountryCodeType
(Optional) The country in which the transaction occurs. See Country Codes
for a list of country codes. By default, it is the merchant’s country of
registration with PayPal.
ButtonLanguagexs: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
(Optional) The price associated with the first menu item
NOTE: If you specify a price, you cannot set a button variable to amount.
Button Language Options
The button language must be compatible with the country identified by the country code.
CountryButton Language Options
All countries not identified below
Austria
Belgium
Canada
z en - English; default
z de - German; default
z en - English
z en - English; default
z nl - Dutch
z fr - French
z en - English; default
z fr - French
China (worldwide)
z en - English; default
z zh - Chinese
28June, 2009Button Manager SOAP API
CountryButton Language Options
Francez fr - French; default
z en - English
Button Manager API Reference
BMUpdateButton API Operation
Germany
Hong Kong
Italy
Japan
Mexico
Netherlands
Poland
Spain
Switzerland
z de - German; default
z en - English
z zh - Chinese; default
z en - English
z it - Italian; default
z en - English
z ja - Japanese; default
z en - English
z es - Spanish; default
z en - English
z nl - Dutch; default
z en - English
z pl - Polish; default
z en - English
z es - Spanish; default
z en - English
z de - German; default
z fr - French
z en - English
United States
z en - English; default
z fr - French
z es - Spanish
z zh - Chinese
BMUpdateButton Response
The response contains the hosted button ID, code for HTML in a website, and code for a link
in email.
Button Manager SOAP APIJune, 200929
Button Manager API Reference
BMUpdateButton API Operation
BMUpdateButton Response Fields
FieldDescription
Websitexs:string
HTML code for web pages
Emailxs:string
Code for email links and links in other documents that support external links
HostedButtonIDxs:string
ID of a PayPal hosted button
BMUpdateButton Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11923Invalid ArgumentThe button image value specified is
invalid.
11924Invalid ArgumentThe button image URL specified is
invalid.
11925Invalid ArgumentThe button type specified is invalid.
11926Invalid DataOne of the parameters specified using
ButtonVar is invalid.
11927Invalid ArgumentThe buy now button text specified is
invalid.
11928Invalid ArgumentThe email or merchant ID specified is
invalid.
11929Invalid DataA cart button must have an item name and
amount specified.
30June, 2009Button Manager SOAP API
Button Manager API Reference
BMUpdateButton API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11930Invalid DataA gift certificate button must have a valid
shopping URL specified.
11931Invalid ArgumentThe subscription button text specified is
invalid.
11932Invalid DataYou must specify a corresponding number
of entries for option names and selections.
11933Invalid DataYou cannot skip index numbers for option
selections. Option selections must be
specified sequentially.
11934Invalid DataYou must specify the same number of
entries for option prices and selections.
11936Invalid DataYou cannot specify both an item price and
prices for individual selections within an
option.
11937Invalid ArgumentA text box name specified is invalid. Text
box names must not exceed 64 characters.
11938Invalid ArgumentThe button code value specified is invalid.
11940Invalid ArgumentAn option name specified is invalid.
Option names must not exceed 64
characters.
11941Invalid ArgumentAn option selection value specified is
invalid. Option selection values must not
exceed 64 characters.
11942Invalid ArgumentAn option price value specified is invalid.
Make sure any punctuation marks are in
the correct places.
11943Invalid ArgumentThe button country value specified is
invalid.
11945Invalid DataThe button country and language code
combination specified is invalid.
11947Invalid ArgumentThe 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.
11948Invalid ArgumentThe amount specified is invalid. Make
sure any punctuation marks are in the
correct places.
Button Manager SOAP APIJune, 200931
Button Manager API Reference
BMButtonSearch API Operation
BMButtonSearch API Operation
Use the BMButtonSearch API operation to obtain a list of your hosted Website Payments
Standard buttons.
z BMButtonSearch Request
z BMButtonSearch Response
z BMButtonSearch Errors
BMButtonSearch Request
The request contains optional fields that are not currently used. All hosted buttons are
automatically requested.
BMButtonSearch Request Fields
FieldDescription
StartDatexs:dateTime
(Required) Starting date for the search, such as 12/01/09
EndDatexs:dateTime
(Optional) Ending date for the search, such as 12/31/09
BMButtonSearch Response
The response contains a list of all hosted buttons and their associated characteristics.
32June, 2009Button Manager SOAP API
Button Manager API Reference
BMButtonSearch API Operation
BMButtonSearch Response Fields
NameDescription
—ebl:ButtonSearchResult
Search results
ButtonSearchResult
HostedButtonIDxs:string
The hosted button ID
HButtonTypexs:string
The hosted button ID
ItemNamexs:string
The item name
ModifyDatexs:dateTime
The date created or last changed
BMButtonSearch Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
Button Manager SOAP APIJune, 200933
Button Manager API Reference
BMGetButtonDetails API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11994Search WarningYou have exceeded the maximum number
of buttons that can be returned. Please
adjust your seach parameters if required.
11997Invalid ArgumentA start date value must be specified.
11998Invalid ArgumentThe start date specified is invalid.
11999Invalid ArgumentThe end date specified is invalid.
BMGetButtonDetails API Operation
Use the BMGetButtonDetails API operation to obtain information about a hosted Website
Payments Standard button. You can use this information to set the fields that have not changed
when updating a button.
z BMGetButtonDetails Request
z BMGetButtonDetails Response
z BMUpdateButton Errors
BMGetButtonDetails Request
The request consists of only the ID of the hosted button whose details you want to obtain.
BMGetButtonDetails Request Fields
FieldDescription
HostedButtonIDxs:string
(Required) The ID of the hosted button whose details you want to obtain.
BMGetButtonDetails Response
The response fields contain all non-inventory information related to the button.
34June, 2009Button Manager SOAP API
Button Manager API Reference
BMGetButtonDetails API Operation
BMGetButtonDetails Response Fields
FieldDescription
ButtonTypeebl:ButtonTypeType
The kind of button. It is one of the following values:
z BUYNOW - Buy Now button
z CART - Add to Cart button
z GIFTCERTIFICATE - Gift Certificate button
z SUBSCRIBE - Subscribe button
z DONATE - Donate button
z UNSUBSCRIBE - Unsubscribe button
z VIEWCART - View Cart button
ButtonCodeebl:ButtonCodeType
The kind of button code. It is one of the following values:
z HOSTED - A secure button stored on PayPal
z ENCRYPTED - An encrypted button, not stored on PayPal
z CLEARTEXT - An unencrypted button, not stored on PayPal
ButtonSubTypeebl:ButtonSubTypeType
The use of button. It is one of the following values:
z PRODUCTS - button is used to purchase products
z SERVICES - button is used to purchase services
HostedButtonIDxs:string
ID of a PayPal hosted button
Button Manager SOAP APIJune, 200935
Button Manager API Reference
BMGetButtonDetails API Operation
FieldDescription
Websitexs:string
HTML code for web pages
Emailxs:string
Code for email links and links in other documents that support external links
ButtonVarxs:string
HTML standard button variables, which are described in HTML Variables for
Website Payments Standard
It is a list of variables, in which n is a digit between 0 and 9, inclusive.
Character length and limitations: 63 single-byte alphanumeric characters each
OptionDetailsns:OptionDetailsType
Menu items
TextBoxxs:string
Text description for a menu item
It is a list of variables, in which
n is a digit between 0 and 2, inclusive.
ButtonImageebl:ButtonImageType
The kind of button image. It is one of the following values:
z REG - regular
z SML - small
z CC - credit card logos
ButtonImageURLxs:string
The button’s URL
BuyNowTextebl:BuyNowTextType
The button text for a Buy Now button. It is one of the following values:
z BUYNOW - button text is Buy Now
z PAYNOW - button text is Pay Now
SubscribeTextebl:SubscribeTextType
The button text for a Subscribe button. It is one of the following values:
z BUYNOW - button text is Buy Now
z SUBSCRIBE - button text is Subscribe
ButtonCountryebl:CountryCodeType
The country in which the transaction occurs. See Country Codes
country codes. By default, it is the merchant’s country of registration with
PayPal.
ButtonLanguagexs:string
The languange in which to display the button text
Character length and limitations: 2 single-byte alphanumeric characters
(Optional) The price associated with the first menu item
NOTE: If you specify a price, you cannot set a button variable to amount.
Button Manager API Reference
BMManageButtonStatus API Operation
BMGetButtonDetails Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11950Invalid DataA hosted button ID must be specified.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11992Invalid ArgumentYou do not have permissions to access this
button. Please check the hosted button ID
and try again.
BMManageButtonStatus API Operation
Use the BMManageButtonStatus API operation to change the status of a hosted button.
Currently, you can only delete a button.
z BMManageButtonStatus Request
z BMManageButtonStatus Response
z BMUpdateButton Errors
Button Manager SOAP APIJune, 200937
Button Manager API Reference
BMManageButtonStatus API Operation
BMManageButtonStatus Request
The request specifies the hosted button’s ID and the status to which you want to set the button.
BMManageButtonStatus Request Fields
FieldDescription
HostedButtonIDxs:string
(Required) The ID of the hosted button whose status you want to change.
ButtonStatusebl:ButtonStatusType
(Required) The new status of the button. It is one of the following values:
z DELETE - the button is deleted from PayPal
BMManageButtonStatus Response
The response does not include any fields that are specific to the BMManageButtonStatus
API operation.
BMManageButtonStatus Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11950Invalid DataA hosted button ID must be specified.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11992Invalid ArgumentYou do not have permissions to access this
button. Please check the hosted button ID
and try again.
38June, 2009Button Manager SOAP API
Button Manager API Reference
BMSetInventory API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11993Invalid ArgumentThe button status value specified is not
valid.
BMSetInventory API Operation
Use the BMSetInventory API operation to set the inventory level and inventory
management features for the specified button. When you set the inventory level for a button,
PayPal can track inventory, calculate the gross profit associated with sales, send you an alert
when inventory drops below a specified quantity, and manage sold out conditions.
z BMSetInventory Request
z BMSetInventory Response
z BMSetInventory Errors
BMSetInventory Request
The request specifies inventory values related to a hosted button as well as inventory values
that are specific to each menu item associated with the button.
Button Manager SOAP APIJune, 200939
Button Manager API Reference
BMSetInventory API Operation
BMSetInventory Request Fields
FieldDescription
HostedButtonIDxs:string
(Required) The ID of the hosted button whose inventory you want to set.
40June, 2009Button Manager SOAP API
FieldDescription
TrackInvxs:string
(Required) Whether to track inventory levels associated with the button. It is
one of the following values:
z 0 - do not track inventory
z 1 - track inventory
TrackPnlxs:string
(Required) Whether to track the gross profit associated with inventory
changes. It is one of the following values:
z 0 - do not track the gross profit
z 1 - track the gross profit
NOTE: The gross profit is calculated as the price of the item less its cost,
multiplied by the change in the inventory level since the last call to
BMSetInventory.
—ebl:ItemTrackingDetails
(Optional) Item tracking details for the button
Button Manager API Reference
BMSetInventory API Operation
OptionIndexxs:string
(Optional) Option index, which identifies the button. Option index 0 is the
menu that contains the price if one exists; otherwise, it is the first menu
without a price.
Character length and limitations: 1 single-byte alphanumeric character
—ebl:OptionTrackingDetails
(Optional) Option tracking details for menu items associated with the button
SoldoutURLxs:string
(Optional) The URL to which the buyer’s browser is redirected when the
inventory drops to 0
NOTE: Specifying a URL in this field also prevents a sale when the inventory
drops to 0; otherwise, sales can continue even when inventory is
unavailable.
Character length and limitations: 127 single-byte alphanumeric characters
Item Tracking Details Fields
ItemNumberxs:string
(Optional) The ID for an item associated with this button
ItemQtyxs:string
The quantity you want to specify for the item associated with this button.
Specify either the absolute quantity in this field or the change in quantity in the
quantity delta field
Button Manager SOAP APIJune, 200941
Button Manager API Reference
BMSetInventory API Operation
ItemQtyDeltaxs:string
The change in quantity you want to specify for the item associated with this
button. Specify either the change in quantity in this field or the absolute
quantity in the item quantity field
ItemAlertxs:string
(Optional) The quantity of the item associated with this button below which
PayPal sends you an email notification
ItemCostxs:string
(Optional) The cost of the item associated with this button
Option Tracking Details Fields
OptionNumberxs:string
(Optional) The menu item’s ID for an option in a dropdown menu
OptionQtyxs:string
The quantity you want to specify for the option associated with this menu item.
Specify either the absolute quantity in this field or the change in quantity in the
quantity delta field
OptionSelectxs:string
(Optional) The menu item’s name in a dropdown menu
OptionQtyDeltaxs:string
The change in quantity you want to specify for the option associated with this
menu item. Specify either the change in quantity in this field or the absolute
quantity in the quantity field
OptionAlertxs:string
(Optional) The quantity of the option associated with this menu item below
which PayPal sends you an email notification
OptionCostxs:string
(Optional) The cost of the option associated with this menu item
Limitations: Value must be a positive number, with no currency symbol. It
must have two decimal places and the decimal separator must be a period (.). It
may have an optional comma (,) for the thousands separator.
BMSetInventory Response
The response consists of a transaction ID.
42June, 2009Button Manager SOAP API
BMSetInventory Response Fields
FieldDescription
TransactionIDxs:string
Transaction ID
BMSetInventory Errors
Button Manager API Reference
BMSetInventory API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11950Invalid DataA hosted button ID must be specified.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11953Invalid DataYou can only track inventory and profit &
loss for buy now, cart or subscription
buttons.
11954Invalid DataA TrackInv value must be specified.
11955Invalid DataA TrackPnl value must be specified.
11956Invalid ArgumentThe TrackInv value specified is invalid.
11957Invalid ArgumentThe TrackPnl value specified is invalid.
11958Invalid DataYou cannot specify both an ItemQty and
ItemQtyDelta value.
11959Invalid DataYou cannot specify both an OptionQty and
OptionQtyDelta value.
11960Invalid DataYou cannot specify item level or option
level inventory when TrackInv is 0.
11961Invalid DataYou must either track inventory by item or
by option when TrackInv is 1. It cannot be
tracked by both together or none at all.
Button Manager SOAP APIJune, 200943
Button Manager API Reference
BMSetInventory API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11964Invalid DataYou must either track inventory and/or
track profit & loss.
11965Invalid DataYou cannot track inventory by item and
cost by option at the same time or vice
versa.
11966Invalid ArgumentItem number specified is invalid. It must
be a string less than 127 characters.
11967Invalid DataYou cannot set inventory for more option
selections than the number of option
selections saved in the button.
11968Invalid DataOption numbers must be unique within an
individual button.
11969Invalid DataAn option name index value must be
specified when tracking inventory or
profit & loss by option.
11970Invalid ArgumentOption name index value specified is
invalid.
11971Invalid DataInventory and/or profit & loss must be
managed by item or an option with price
when one is defined.
11972Invalid DataOption name index value specified does
not exist.
11973Invalid DataItemQty and/or ItemQtyDelta must be an
integer.
11974Invalid DataAn item quantity or item quantity delta
value cannot be specified when TrackInv
is 0.
11975Invalid DataThe number of option quantity or option
quantity delta values specified is greater
than the number of option selections in the
saved button.
11976Invalid DataYou must specify either option quantity or
option quantity delta values with a valid
integer value.
11977Invalid DataAn option quantity or option quantity
delta value must not be specified when
TrackInv is 0.
11978Invalid ArgumentItem alert must be specified as a positive
integer.
44June, 2009Button Manager SOAP API
Button Manager API Reference
BMGetInventory API Operation
Error
CodeShort MessageLong MessageCorrecting This Error...
11979Invalid ArgumentItem alert must not be specified when
TrackInv is 0.
11980Invalid DataThe number of option alert values
specified is greater than the number of
option selections in the saved button.
11981Invalid ArgumentOption alert values must be specified as a
positive integer.
11982Invalid ArgumentOption alert values cannot be specified
when TrackInv is 0.
11983Invalid ArgumentItem cost value must be specified when
tracking profit & loss by item.
11984Invalid ArgumentThe item cost value specified is invalid.
11985Invalid ArgumentAn item cost value cannot be specified
when TrackPnl is 0.
11986Invalid DataThe number of option cost values
specified is greater than the number of
option selections in the saved button.
11987Invalid ArgumentOption cost values must be specified when
tracking profit & loss by option.
11988Invalid ArgumentAn option cost value specified is invalid.
11989Invalid ArgumentAn option cost value cannot be specified
when TrackPnl is 0.
11990Invalid ArgumentThe sold out URL specified is invalid.
11992Invalid ArgumentYou do not have permissions to access this
button. Please check the hosted button ID
and try again.
BMGetInventory API Operation
Use the BMGetInventory API operation to determine the inventory levels and other
inventory-related information for a button and menu items associated with the button.
Typically, you call BMGetInventory to obtain field values before calling BMSetInventory
to change the inventory levels.
z BMGetInventory Request
z BMGetInventory Response
z BMGetInventory Errors
Button Manager SOAP APIJune, 200945
Button Manager API Reference
BMGetInventory API Operation
BMGetInventory Request
The hosted button ID identifies the button whose inventory you want to track.
BMGetInventory Request Fields
FieldDescription
HostedButtonIDxs:string
(Required) The ID of the hosted button whose inventory information you want
to obtain.
BMGetInventory Response
The response fields contain inventory information related to the button.
BMGetInventory Response Fields
FieldDescription
HostedButtonIDxs:string
The ID of the hosted button whose inventory you want to set.
46June, 2009Button Manager SOAP API
FieldDescription
TrackInvxs:string
Whether to track inventory levels associated with the button. It is one of the
following values:
z 0 - do not track inventory
z 1 - track inventory
TrackPnlxs:string
Whether to track the gross profit associated with inventory changes. It is one
of the following values:
z 0 - do not track the gross profit
z 1 - track the gross profit
NOTE: The gross profit is calculated as the price of the item less its cost,
multiplied by the change in the inventory level since the last call to
BMSetInventory.
—ebl:ItemTrackingDetails
Item tracking details for the button
Button Manager API Reference
BMGetInventory API Operation
OptionIndexxs:string
Option index, which identifies the button. Option index 0 is the menu that
contains the price if one exists; otherwise, it is the first menu without a price.
Character length and limitations: 1 single-byte alphanumeric character
—ebl:OptionTrackingDetails
Option tracking details for menu items associated with the button
SoldoutURLxs:string
The URL to which the buyer’s browser is redirected when the inventory drops
to 0
NOTE: A value in this field also prevents a sale when the inventory drops to 0;
otherwise, sales can continue even when inventory is unavailable.
Character length and limitations: 127 single-byte alphanumeric characters
Item Tracking Details Fields
ItemNumberxs:string
The ID for an item associated with this button
ItemQtyxs:string
The current inventory level of the item associated with this button
ItemQtyDeltaxs:string
Not used
ItemAlertxs:string
The quantity of the item associated with this button below which PayPal sends
you an email notification
Button Manager SOAP APIJune, 200947
Button Manager API Reference
BMGetInventory API Operation
ItemCostxs:string
The cost of the item associated with this button
Option Tracking Details Fields
OptionNumberxs:string
The menu item’s ID for an option in a dropdown menu
OptionQtyxs:string
The current inventory level of the option associated with this menu item
OptionSelectxs:string
The menu item’s name in a dropdown menu
OptionQtyDeltaxs:string
Not used
OptionAlertxs:string
The quantity of the option associated with this menu item below which PayPal
sends you an email notification
OptionCostxs:string
The cost of the option associated with this menu item
BMGetInventory Errors
Error
CodeShort MessageLong MessageCorrecting This Error...
10001Internal ErrorInternal Error
11950Invalid DataA hosted button ID must be specified.
11951Invalid ArgumentThe hosted button ID specified is invalid.
11953Invalid DataYou can only track inventory and profit &
loss for buy now, cart or subscription
buttons.
11991Invalid DataThe hosted button id specified does not
have any inventory or cost associated with
it.
11992Invalid ArgumentYou do not have permissions to access this
button. Please check the hosted button ID
and try again.
48June, 2009Button Manager SOAP API
A
HTML Variables for Website
Payments Standard
This appendix provides reference information for all HTML variables supported for use with
Buy Now, Donation, Subscribe, Add to Cart, and View Cart buttons, as well as HTML
variables supported the Cart Upload command.
Read the following topics to learn about the kinds of HTML variables that you can use:
z “Technical HTML Variables” on page 49
z “HTML Variables for Individual Items” on page 50
z “HTML Variables for Payment Transactions” on page 56
z “HTML Variables for Shopping Carts” on page 58
z “HTML Variables for Subscribe Buttons” on page 60
z “HTML Variables for Displaying PayPal Checkout Pages” on page 63
z “HTML Variables for Prepopulating PayPal Checkout Pages” on page 66
Technical HTML Variables
Technical HTML variables control how PayPal responds technically when people click Buy
Now, Donation, Subscribe, Add to Cart, and View Cart buttons or when third party or custom
carts initiate payment processing with the Cart Upload command. They also control how your
buttons interact with special PayPal features.
Button Manager SOAP APIJune, 200949
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Allowable Values for the cmd HTML Variable
Value of cmdDescription
_xclickThe button that the person clicked was a Buy Now button.
_donationsThe button that the person clicked was a Donate button.
_xclick-subscriptionsThe button that the person clicked was a Subscribe button.
_oe-gift-certificateThe button that the person clicked was a Buy Gift Certificate button.
_cartFor shopping cart purchases; these additional variables specify the
kind of shopping cart button that the person clicked:
z add – Add to Cart buttons for the PayPal Shopping Cart
z display – View Cart buttons for the PayPal Shopping Cart
z upload – The Cart Upload command for third party carts
_s-xclickThe button that the person clicked was protected from tampering by
using encryption, or the button was saved in the merchant’s PayPal
account. PayPal determines which kind of button was clicked by
decoding the encrypted code or by looking up the saved button in the
merchant’s account.
HTML Variables for Special PayPal Features
Required or
Name
OptionalDescription
notify_urlOptionalThe URL to which PayPal posts information about the
transaction, in the form of Instant Payment Notification
messages.
hosted_button
_id
Required for
buttons that
have been
saved in PayPal
accounts;
otherwise, not
allowed.
The identifier of a button that was saved in a merchant’s
PayPal account. Allowable values are assigned by PayPal
when payments buttons are first created and saved
merchants’ PayPal accounts.
NOTE: A merchant’s PayPal account can have a maximum
of 1,000 saved payment buttons.
HTML Variables for Individual Items
HTML variables for individual items specify information about a product or service for Buy
Now and Add to Cart buttons, or they specify information about a contribution for Donate
buttons.
Character
Length
255
See
description.
50June, 2009Button Manager SOAP API
HTML Variables for Individual Items
Required
or
Name
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Character
Length
amountSee
description.
The price or amount of the product, service, or contribution,
not including shipping, handling, or tax. If omitted from Buy
Now or Donate buttons, payers enter their own amount at the
time of payment.
z Required for Add to Cart buttons
z Optional for Buy Now and Donate buttons
z Not used with Subscribe or Buy Gift Certificate buttons
discount_amountOptionalDiscount amount associated with an item.
It must be less than the selling price of the item. If you specify
discount_amount and discount_amount2 is not defined, then
this flat amount is applied regardless of the quantity of items
purchased.
Valid only for Buy Now and Add to Cart buttons.
discount_amount2OptionalDiscount amount associated with each additional quantity of
the item.
It must be equal to or less than the selling price of the item. A
discount_amount must also be specified as greater than or
equal to 0 for discount_amount2 to take effect.
Valid only for Buy Now and Add to Cart buttons.
discount_rateOptionalDiscount rate (percentage) associated with an item.
It must be set to a value less than 100. If you do not set
discount_rate2, the value in discount_rate applies
only to the first item regardless of the quantity of items
purchased.
Valid only for Buy Now and Add to Cart buttons.
discount_rate2OptionalDiscount rate (percentage) associated with each additional
quantity of the item.
It must be equal to or less 100. A discount_rate must also
be specified as greater than or equal to 0 for
discount_rate2 to take effect.
Valid only for Buy Now and Add to Cart buttons.
discount_numOptionalNumber of additional quantities of the item to which the
discount applies.
Applicable when you use discount_amount2 or
discount_rate2. Use this variable to specify an upper limit on
the number of discounted items.
Valid only for Buy Now and Add to Cart buttons.
Button Manager SOAP APIJune, 200951
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Required
or
Name
OptionalDescription
Character
Length
item_nameSee
description.
Description of item. If omitted, payers enter their own name
at the time of payment.
z Optional for Buy Now, Donate, Subscribe and Add to Cart
buttons
z Not used with Buy Gift Certificate buttons
item_numberOptionalPass-through variable for you to track product or service
purchased or the contribution made. The value you specify
passed back to you upon payment completion.
quantityOptionalNumber of items. If profile-based shipping rates are
configured with a basis of quantity, the sum of quantity
values is used to calculate the shipping charges for the
transaction. PayPal appends a sequence number to uniquely
identify the item in the PayPal Shopping Cart (e.g., quantity1,
quantity2).
NOTE: The value for quantity must be a positive integer.
Null, zero, or negative numbers are not allowed.
shippingOptionalThe cost of shipping this item. If you specify shipping and
shipping2 is not defined, this flat amount is charged
regardless of the quantity of items purchased.
This use of the shipping variable is valid only for Buy Now
and Add to Cart buttons.
Default – If profile-based shipping rates are configured,
buyers are charged an amount according to the shipping
methods they choose.
127
127
shipping2OptionalThe cost of shipping each additional unit of this item. If
omitted and profile-based shipping rates are configured,
buyers are charged an amount according to the shipping
methods they choose.
Valid only for Buy Now and Add to Cart buttons.
taxOptionalTransaction-based tax override variable. Set this to a flat tax
amount to apply to the transaction regardless of the buyer’s
location. This value overrides any tax settings set in your
account profile. Valid only for Buy Now and Add to Cart
buttons. Default – Profile tax settings, if any, apply.
tax_rateOptionalTransaction-based tax override variable. Set this to a
6
percentage that will be applied to amount multiplied the
quantity selected during checkout. This value overrides any
tax settings set in your account profile. Allowable values are
numbers 0.001 through 100. Valid only for Buy Now and
Add to Cart buttons. Default – Profile tax settings, if any,
apply.
52June, 2009Button Manager SOAP API
Name
Required
or
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Character
Length
undefined_
quantity
Optional1 – allows buyers to specify the quantity.
z Optional for Buy Now buttons
z Not used with other buttons
weightOptionalWeight of items. If profile-based shipping rates are
configured with a basis of weight, the sum of weight values
is used to calculate the shipping charges for the transaction.
weight_unitOptionalThe unit of measure if weight is specified. Allowable values:
z lbs
z kgs
The defaults is lbs.
on0OptionalFirst option field name and label. The os0 variable contains
the corresponding value for this option field. For example, if
on0 is size, os0 could be large.
z Optional for Buy Now, Subscribe, and Add to Cart buttons
z Not used with Donate or Buy Gift Certificate buttons
on1OptionalSecond option field name and label. The os1 variable
contains the corresponding value for this option field. For
example, if on1 is color then os1 could be blue.
You can specify a maximum of 7option field names (6 with
Subscribe buttons) by incrementing the option name index
(on0 through on6).
z Optional for Buy Now, Subscribe, and Add to Cart buttons
z Not used with Donate or Buy Gift Certificate buttons
1
64
64
Button Manager SOAP APIJune, 200953
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Required
or
Name
OptionalDescription
Character
Length
os0OptionalOption selection of the buyer for the first option field, on0. If
the option field is a dropdown menu or a set of radio buttons,
each allowable value should be no more than 64 characters. If
buyers enter this value in a text field, there is a 200-character
limit.
NOTE: The option field on0 must also be defined. For
example, it could be size.
For priced options, include the price and currency symbol in
the text of the option selections, as the following sample code
shows:
<option value="small">small - $10.00</option>
Add a corresponding option_select0 and
option_amount0 variable for each priced option. Priced
options are supported only for Buy Now and Add to Cart
buttons. Only one dropdown menu option selection can have
priced options.
z Optional for Buy Now, Subscribe, and Add to Cart buttons
z Not used with Donate or Buy Gift Certificate buttons
os1OptionalOption selection of the buyer for the second option field, on1.
If the option field is a dropdown menu or a set of radio
buttons, each allowable value should be no more than 64
characters. If buyers enter this value in a text field, there is a
200-character limit.
You can specify a maximum of 7 option selections (6 with
Subscribe buttons) by incrementing the option selection index
(os0 through os6). You can implement up to 5 option
selections as dropdown menus and up to 2 option selections
as test boxes.
NOTE: A corresponding option field (on0 through on6) must
defined.
z Optional for Buy Now, Subscribe, and Add to Cart buttons
z Not used with Donate or Buy Gift Certificate buttons
64 or 200
See
description.
64 or 200
See
description.
option_indexSee
description.
The cardinal number of the option field, on0 through on9,
that has product options with different prices for each option.
You must include option_index if the option field with prices
is not on0.
z Optional for Buy Now and Add to Cart buttons
z Not used with Donate, Subscribe, or Buy Gift Certificate
buttons
Default – 0
54June, 2009Button Manager SOAP API
Name
Required
or
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Individual Items
Character
Length
option_select0OptionalFor priced options, the value of the first option selection of
the on0 dropdown menu. The values must match exactly, as
the next sample code shows:
You can specify a maximum of ten option amounts by
incrementing the option amount index (option_amount0
through option_amount9).
NOTE: A corresponding option selection in os0 must also be
set.
z Optional for Buy Now and Add to Cart buttons
z Not used with Donate, Subscribe, or Buy Gift Certificate
buttons
HTML Variables for Payment Transactions
HTML variables for payment transactions provide information about entire transactions,
regardless of the individual items involved with the payment. You can use these variables with
Add to Cart buttons and the Cart Upload command.
64
56June, 2009Button Manager SOAP API
HTML Variables for Payment Transactions
Required
or
Name
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Payment Transactions
Character
Length
address_
override
Optional1 – The address specified in prepopulation variables overrides the
PayPal member’s stored address. The payer is shown the passed-in
address but cannot edit it. No address is shown if the address is not
valid, such as missing required fields like country, or is not
included at all.
currency_
OptionalThe currency of the payment. The default is USD. 3
code
customOptionalPassthrough variable never presented to the payer.
Default – No variable is passed back to you.
handlingOptionalHandling charges. This is not quantity-specific. The same handling
cost applies, regardless of the number of items on the order.
Default – No handling charges are included.
invoiceOptionalPassthrough variable you can use to identify your invoice number
for this purchase.
Default – No variable is passed back to you.
shippingOptionalThe cost of shipping the entire order contained in third-party
shopping carts.
This use of the shipping variable is valid only for the Cart Upload
command.
Default – If profile-based shipping rates are configured, buyers are
charged an amount according to the shipping methods they choose.
1
256
127
tax_cartOptionalCart-wide tax, overriding any individual item tax_
x value
weight_cartOptionalIf profile-based shipping rates are configured with a basis of
weight, PayPal uses this value to calculate the shipping charges for
the transaction. This value overrides the weight values of
individual items.
weight_unitOptionalThe unit of measure if weight_cart is specified. Allowable
values:
z lbs
z kgs
The default value is lbs.
Button Manager SOAP APIJune, 200957
HTML Variables for Website Payments Standard
HTML Variables for Shopping Carts
HTML Variables for Shopping Carts
HTML variables for shopping carts can be used with Add to Cart buttons, as well as with third
party shopping carts or custom carts that initiate payment processing with the Cart Upload
command.
58June, 2009Button Manager SOAP API
HTMLVariables for Shopping Carts
HTML Variables for Website Payments Standard
HTML Variables for Shopping Carts
Required
Name
addSee
or OptionalDescription
Add an item to the PayPal Shopping Cart.
description
This variable must be set as follows:
add="1"
The alternative is the display="1" variable, which displays
the contents of the PayPal Shopping Cart to the buyer.
If both add and display are specified, display takes
precedence.
amountRequiredPrice of the item or the total price of all items in the shopping
cart.
businessRequiredYour PayPal ID or an email address associated with your
PayPal account. Email addresses must be confirmed.
discount_amount
_cart
OptionalSingle discount amount to be charged cart-wide.
It must be less than the selling price of all items combined in
the cart. This variable overrides any individual item
discount_amount_
x values, if present.
Applies only to the Cart Upload command.
discount_amount
_
x
OptionalThe discount amount associated with item x.
It must be less than the selling price of the associated item.
This amount is added with any other item discounts in the
cart.
Applies only to the Cart Upload command.
Characte
r Length
1
discount_rate_c
art
OptionalSingle discount rate (percentage) to be charged cart-wide.
It must be set to a value less than 100. The variable overrides
any individual item discount_rate_
x values, if present.
Applies only to the Cart Upload command.
discount_rate_
xOptionalThe discount rate associated with item x.
It must be set to a value less than 100. The variable takes into
account all quantities of item
x.
Applies only to the Cart Upload command.
displaySee
description.
Display the contents of the PayPal Shopping Cart to the
buyer. This variable must be set as follows:
display="1"
1
The alternative is the add="1" variable, which adds an item
to the PayPal Shopping Cart.
If both add and display are specified, display takes
precedence.
Button Manager SOAP APIJune, 200959
HTML Variables for Website Payments Standard
HTML Variables for Subscribe Buttons
Required
Name
or OptionalDescription
handling_ cartOptionalSingle handling fee to be charged cart-wide. If
handling_cart is used in multiple Add to Cart buttons, the handling_cart value of the first item is used.
item_nameRequiredName of the item or a name for the entire Shopping Cart
paymentactionOptionalIndicates whether the transaction is payment on a final sale or
an authorization for a final sale, to be captured later.
Allowable values:
z sale
z authorization
z order
The default value is sale. Set the value to authorization
to place a hold on the PayPal account for the authorized
amount. Set the value to order to authorize the transaction
without placing a hold on the PayPal account.
IMPORTANT: If you set paymentaction to order, you
must use the Authorization & Capture API to
authorize and capture the transaction
payments. The merchant tools on the PayPal
websitel let you capture payments only for
authorizations, not for orders.
Characte
r Length
shopping_urlOptionalThe URL of the page on the merchant website that buyers
return to when they click the Continue Shopping button on
the PayPal Shopping Cart page.
uploadSee
description
Upload the contents of a third party shopping cart or a custom
shopping cart.
This variable must be set as follows:
upload="1"
The alternatives are the add="1" variable and the
display="1" variable, which are used with the PayPal
Shopping Cart.
HTML Variables for Subscribe Buttons
HTML variables for Subscribe buttons set the terms of subscriptions and their recurring
payments.
1
60June, 2009Button Manager SOAP API
HTML Variables for Website Payments Standard
HTML Variables for Subscribe Buttons
HTML Variables for Subscribe Buttons
Required
or
Name
businessRequiredYour PayPal ID or an email address associated with your PayPal
item_nameOptionalDescription of item being sold (maximum 127 characters). If you
OptionalDescription
account. Email addresses must be confirmed.
are collecting aggregate payments, this can include a summary of
all items purchased, tracking numbers, or generic terms such as
“subscription.” If omitted, customer will see a field in which they
have the option of entering an Item Name
Character
Length
currency_codeOptionalThe currency of prices for trial periods and the subscription. The
default is USD.
a1OptionalTrial period 1 price. For a free trial period, specify 0.
p1See
description.
Trial period 1 duration. Required if you specify a1. Specify an
integer value in the allowable range for the units of duration that
you specify with t1.
t1See
description.
Trial period 1 units of duration. Required if you specify a1.
Allowable values:
z D – for days; allowable range for p1 is 1 to 90
z W – for weeks; allowable range for p1 is 1 to 52
z M – for months; allowable range for p1 is 1 to 24
z Y – for years; allowable range for p1 is 1 to 5
a2OptionalTrial period 2 price. Can be specified only if you also specify a1.
p2See
description.
Trial period 2 duration. Required if you specify a2. Specify an
integer value in the allowable range for the units of duration that
you specify with t2.
t2See
description.
Trial period 2 units of duration. Allowable values:
z D – for days; allowable range for p2 is 1 to 90
z W – for weeks; allowable range for p2 is 1 to 52
z M – for months; allowable range for p2 is 1 to 24
z Y – for years; allowable range for p2 is 1 to 5
3
2
1
2
1
a3RequiredRegular subscription price.
p3RequiredSubscription duration. Specify an integer value in the allowable
2
range for the units of duration that you specify with t3.
t3RequiredRegular subscription units of duration. Allowable values:
z D – for days; allowable range for p3 is 1 to 90
z W – for weeks; allowable range for p3 is 1 to 52
z M – for months; allowable range for p3 is 1 to 24
z Y – for years; allowable range for p3 is 1 to 5
subscribers cancel their subscriptions before the end of the current
billing cycle or you limit the number of times that payments recur
with the value that you specify for srt.
Allowable values:
z 0 – subscription payments do not recur
z 1 – subscription payments recur
The default is 0.
srtOptionalRecurring times. Number of times that subscription payments
recur. Specify an integer above 1. Valid only if you specify
src="1".
sraOptionalReattempt on failure. If a recurring payment fails, PayPal attempts
to collect the payment two more times before canceling the
subscription.
Allowable values:
z 0 – do not reattempt failed recurring payments
z 1 – reattempt failed recurring payments before canceling
The default is 0.
no_noteRequiredDo not prompt payers to include a note with their payments.
Allowable values for Subscribe buttons:
z 1 – hide the text box and the prompt
For Subscribe buttons, always include no_note and set it to 1.
1
1
1
1
customOptionalUser-defined field which will be passed through the system and
255
returned in your merchant payment notification email. This field
will not be shown to your subscribers.
invoiceOptionalUser-defined field which must be unique with each subscription.
127
The invoice number will be shown to subscribers with the other
details of their transactions
z 0 – allows subscribers to only create new subscriptions
z 1 – allows subscribers to modify their current subscriptions or
1
sign up for new ones
z 2 – allows subscribers to only modify their current
subscriptions
The default value is 0.
usr_manageOptionalSet to 1 to have PayPal generate usernames and initial passwords
1
for subscribers.
62June, 2009Button Manager SOAP API
HTML Variables for Website Payments Standard
HTML Variables for Displaying PayPal Checkout Pages
HTML Variables for Displaying PayPal Checkout Pages
HTML variables for displaying PayPal checkout pages control how the pages appear and
function.
Button Manager SOAP APIJune, 200963
HTML Variables for Website Payments Standard
HTML Variables for Displaying PayPal Checkout Pages
HTML Variables for Displaying PayPal Checkout Pages
Required
or
Name
OptionalDescription
Character
Length
page_styleOptionalThe custom payment page style for checkout pages. Allowable
values:
z paypal – use the PayPal page style
z primary – use the page style that you marked as primary in
your account profile
z page_style_name – use the custom payment page style
from your account profile that has the specified name
The default is primary if you added a custom payment page
style to your account profile. Otherwise, the default is paypal.
image_urlOptionalThe URL of the 150x50-pixel image displayed as your logo in the
upper left corner of the PayPal checkout pages.
Default – Your business name, if you have a Business account, or
your email address, if you have Premier or Personal account.
cpp_header_
image
OptionalThe image at the top left of the checkout page. The image’s
maximum size is 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored only on a
secure (https) server.
cpp_
headerback_
color
cpp_
headerborder
_color
OptionalThe background color for the header of the checkout page.
Valid value is case-insensitive six-character HTML hexadecimal
color code in ASCII.
OptionalThe border color around the header of the checkout page. The
border is a 2-pixel perimeter around the header space, which has
a maximum size of 750 pixels wide by 90 pixels high.
Valid value is case-insensitive six-character HTML hexadecimal
color code in ASCII.
30
1,024
No limit
6
6
cpp_payflow_
color
OptionalThe background color for the checkout page below the header.
Valid value is case-insensitive six-character HTML hexadecimal
6
color code in ASCII.
NOTE: Background colors that conflict with PayPal’s error
messages are not allowed; in these cases, the default
color is white.
csOptionalThe background color of the checkout page. Allowable values:
z 0 – background color is white
z 1 – background color is black
1
The default is 0.
64June, 2009Button Manager SOAP API
Name
Required
or
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Displaying PayPal Checkout Pages
Character
Length
lcOptionalThe language of the login or sign-up page that subscribers see
when they click the Subscribe button. If unspecified, the
language is determined by a PayPal cookie in the subscriber’s
browser. If there is no PayPal cookie, the default language is U.S.
English.
For allowable values, see .
no_noteOptionalDo not prompt payers to include a note with their payments.
Allowable values:
z 0 – provide a text box and prompt for the note
z 1 – hide the text box and the prompt
The default is 0.
cnOptionalLabel that appears above the note field. This value is not saved
and will not appear in any of your notifications. If omitted, the
default label above the note field is “Add special instructions to
merchant.” The cn variable is not valid with Subscribe buttons or
if you include no_note="1".
no_shippingOptionalDo not prompt payers for shipping address. Allowable values:
z 0 – prompt for an address, but do not require one
z 1 – do not prompt for an address
z 2 – prompt for an address, and require one
The default is 0.
2
1
90
1
returnOptionalThe URL to which the payer’s browser is redirected after
completing the payment; for example, a URL on your site that
displays a “Thank you for your payment” page.
Default – The browser is redirected to a PayPal web page.
rmOptionalReturn method. The FORM METHOD used to send data to the URL
specified by the return variable after payment completion.
Allowable values:
z 0 – all shopping cart transactions use the GET method
z 1 – the payer’s browser is redirected to the return URL by the
GET method, and no transaction variables are sent
z 2 – the payer’s browser is redirected to the return URL by the
POST method, and all transaction variables are also posted
The default is 0.
NOTE: The rm variable takes effect only if the return variable
is also set.
1,024
1
Button Manager SOAP APIJune, 200965
HTML Variables for Website Payments Standard
HTML Variables for Prepopulating PayPal Checkout Pages
Required
or
Name
OptionalDescription
Character
Length
cbtOptionalSets the text for the Return to Merchant button on the PayPal
Payment Complete page. For Business accounts, the return
button displays your business name in place of the word
“Merchant” by default. For Donate buttons, the text reads
“Return to donations coordinator” by default.
NOTE: The return variable must also be set.
cancel_
return
OptionalA URL to which the payer’s browser is redirected if payment is
cancelled; for example, a URL on your website that displays a
“Payment Canceled” page.
Default – The browser is redirected to a PayPal web page.
60
1,024
HTML Variables for Prepopulating PayPal Checkout Pages
HTML variables for prepopulating PayPal checkout pages let you specify information about
the payer.
HTML Variables for Prepopulating Checkout Pages With Payer Information
Required
Name
or
OptionalDescription
Character
Length
address1Optional Street (1 of 2 fields)100
address2Optional Street (2 of 2 fields)100
cityOptional City40
countryOptionalSets shipping and billing country. 2
first_nameOptional First name32
last_nameOptionalLast name64
lcOptional Sets the payer’s language for the billing information/log-in page
only. The default is US.
charsetOptional Sets the character encoding for the billing information/log-in
page, for the information you send to PayPal in your HTML
button code, and for the information that PayPal returns to you as
a result of checkout processes initiated by the payment button.
The default is based on the character encoding settings in your
account profile.
night_
phone_a
Optional The area code for U.S. phone numbers, or the country code for
phone numbers outside the U.S. This will prepopulate the payer’s
home phone number.
2
21
See
description.
66June, 2009Button Manager SOAP API
Name
Required
or
OptionalDescription
HTML Variables for Website Payments Standard
HTML Variables for Prepopulating PayPal Checkout Pages
Character
Length
night_
phone_b
night_
phone_c
stateOptionalState; use Official U.S. Postal Service Abbreviations
zipOptional Postal code32
Optional The three-digit prefix for U.S. phone numbers, or the entire
phone number for phone numbers outside the U.S., excluding
country code. This will prepopulate the payer’s home phone
number.
Optional The four-digit phone number for U.S. phone numbers. This will
prepopulate the payer’s home phone number.
.2
See
description.
See
description.
Button Manager SOAP APIJune, 200967
HTML Variables for Website Payments Standard
HTML Variables for Prepopulating PayPal Checkout Pages
68June, 2009Button Manager SOAP API
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.