BMSetInventory API Operation (NVP)

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

BMSetInventory Request

The request specifies inventory values related to a hosted button as well as inventory values that are specific to each menu item.

BMSetInventory Request Fields

Field

Description

METHOD

(Required) BMSetInventory

HOSTEDBUTTONID

(Required) The ID of the hosted button whose inventory you want to set.

TRACKINV

(Required) Whether to track inventory levels associated with the button. Value is:

  • 0 - do not track inventory

  • 1 - track inventory

TRACKPNL

(Required) Whether to track the gross profit associated with inventory changes. Value is:

  • 0 - do not track the gross profit

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

OPTIONNAMEINDEX

(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

SOLDOUTURL

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

REUSEDIGITALDOWNLOADKEYS

(Optional) Whether to reuse download keys:

  • 0 - do not reuse keys (default)

  • 1 - reuse keys

Note: If you do not reuse the download keys, you must replenish the keys when you sell out of the product being downloaded.

APPENDDIGITALDOWNLOADKEYS

(Optional) Whether to append download keys:


  • 0 - do not append keys (default)

  • 1 - append keys

Note: If you do not append the download keys, unused keys will be replaced.

L_DIGITALDOWNLOADKEYSn

(Conditional) One or more digital download keys, up to a maximum of 1,000 keys. This field is required if REUSEDIGITALDOWNLOADKEYS and APPENDDIGITALDOWNLOADKEYS are set to 1.

The variable n in the field name is a number between 0 and 999, inclusive, that specifies the key.

Character length and limitations: 1,000 single-byte alphanumeric characters each.

Item Tracking Details Fields

ITEMNUMBER

(Optional) The ID for an item associated with this button.

ITEMQTY

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.

ITEMQTYDELTA

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.

ITEMALERT

(Optional) The quantity of the item associated with this button below which PayPal sends you an email notification.

ITEMCOST

(Optional) The cost of the item associated with this button.

Option Tracking Details Fields

L_OPTIONNUMBERn

(Optional) The menu item's ID for an option in a dropdown menu

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

L_OPTIONQTYn

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

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

L_OPTIONSELECTn

(Optional) The menu item's name in a dropdown menu

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

L_OPTIONQTYDELTAn

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.

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

L_OPTIONALERTn

(Optional) The quantity of the option associated with this menu item below which PayPal sends you an email notification

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

L_OPTIONCOSTn

(Optional) The cost of the option associated with this menu item

It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.

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 contains only the transaction ID.

BMSetInventory Response Fields

Field

Description

TRANSACTIONID

Transaction ID

BMSetInventory Errors


You can only track inventory and profit & loss for buy now, cart or subscription buttons.
Error code Short and long messages User action
10001 Internal Error
Internal Error
To learn more about possible causes and corrective actions, see What is API error code 10001?.
11950 Invalid Data
A hosted button ID must be specified.
11951 Invalid Argument
The hosted button ID specified is invalid.
11951 Invalid Argument
The hosted button ID specified is invalid.
11953 Invalid Data
11954 Invalid Data
A TrackInv value must be specified.
11955 Invalid Data
A TrackPnl value must be specified.
11956 Invalid Argument
The TrackInv value specified is invalid.
11957 Invalid Argument
The TrackPnl value specified is invalid.
11958 Invalid Data
You cannot specify both an ItemQty and ItemQtyDelta value.
11959 Invalid Data
You cannot specify both an OptionQty and OptionQtyDelta value.
11960 Invalid Data
You cannot specify item level or option level inventory when TrackInv is 0.
11961 Invalid Data
You must either track inventory by item or by option when TrackInv is 1. It cannot be tracked by both together or none at all.
11964 Invalid Data
You must either track inventory and/or track profit & loss.
11965 Invalid Data
You cannot track inventory by item and cost by option at the same time or vice versa.
11966 Invalid Argument
Item number specified is invalid. It must be a string less than 127 characters.
11967 Invalid Data
You cannot set inventory for more option selections than the number of option selections saved in the button.
11968 Invalid Data
Option numbers must be unique within an individual button.
11969 Invalid Data
An option name index value must be specified when tracking inventory or profit & loss by option.
11970 Invalid Argument
Option name index value specified is invalid.
11971 Invalid Data
Inventory and/or profit & loss must be managed by item or an option with price when one is defined.
11972 Invalid Data
Option name index value specified does not exist.
11973 Invalid Data
ItemQty and/or ItemQtyDelta must be an integer.
11974 Invalid Data
An item quantity or item quantity delta value cannot be specified when TrackInv is 0.
11975 Invalid Data
The number of option quantity or option quantity delta values specified is greater than the number of option selections in the saved button.
11976 Invalid Data
You must specify either option quantity or option quantity delta values with a valid integer value.
11977 Invalid Data
An option quantity or option quantity delta value must not be specified when TrackInv is 0.
11978 Invalid Argument
Item alert must be specified as a positive integer.
11979 Invalid Argument
Item alert must not be specified when TrackInv is 0.
11980 Invalid Data
The number of option alert values specified is greater than the number of option selections in the saved button.
11981 Invalid Argument
Option alert values must be specified as a positive integer.
11982 Invalid Argument
Option alert values cannot be specified when TrackInv is 0.
11983 Invalid Argument
Item cost value must be specified when tracking profit & loss by item.
11984 Invalid Argument
The item cost value specified is invalid.
11985 Invalid Argument
An item cost value cannot be specified when TrackPnl is 0.
11986 Invalid Data
The number of option cost values specified is greater than the number of option selections in the saved button.
11987 Invalid Argument
Option cost values must be specified when tracking profit & loss by option.
11988 Invalid Argument
An option cost value specified is invalid.
11989 Invalid Argument
An option cost value cannot be specified when TrackPnl is 0.
11990 Invalid Argument
The sold out URL specified is invalid.

12210

Invalid Argument
The currency code value specified is invalid.