browse APIv1_beta.21.0

addItem

POST
/shopping_cart/add_item
Experimental Release This is an Experimental method.

This method creates an eBay cart for the eBay member, if one does not exist, and adds items to that cart. Because a cart never expires, any item added to the cart will remain in the cart until it is removed.

To use this method, you must submit a RESTful item ID and the quantity of the item. If the quantity value is greater than the number of available, the quantity value is changed to the number available and a warning is returned. For example, if there are 15 baseballs available and you set the quantity value to 50, the service automatically changes the value of quantity to 15.

The response returns all the items in the eBay member's cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API. The quantity and state of an item changes often. If the item becomes "unavailable" such as, when the listing has ended or the item is out of stock, whether it has just been added to the cart or has been in the cart for some time, the item will be returned in the unavailableCartItems container.

Note: There are differences between how legacy APIs, such as Finding, and RESTful APIs, such as Browse, return the identifier of an "item" and what the item ID represents. If you have an item ID from one of the legacy APIs, you can use the legacy item ID with the getItemByLegacyId method to retrieve the RESTful ID for that item. For more information about how to use legacy IDs with the Buy APIs, see Legacy API compatibility in the Buying Integration guide.

URLs for this method

  • Production URL: https://api.ebay.com/buy/browse/v1/shopping_cart/
  • Sandbox URL: https://api.sandbox.ebay.com/buy/browse/v1/shopping_cart/

    Note: This method is not available in the eBay API Explorer.

Restrictions

  • This method can be used only for eBay members.
  • You can add only items with a FIXED_PRICE that accept PayPal as a payment.

For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI (production)

POST https://api.ebay.com/buy/browse/v1/shopping_cart/add_item

URI parameters

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/buy.shopping.cart

See OAuth access tokens for more information.

Input container/fieldTypeDescription
itemIdstringThe eBay RESTful identifier of the item you want added to the cart.

RESTful Item ID Format: v1|#|#
For example:
v1|272394640372|0
v1|162846450672|461882996982

For more information about item ID for RESTful APIs, see the Legacy API compatibility section of the Buy APIs Overview.

Maximum number of items in a cart: 100

Occurrence: Required

quantityintegerThe number of this item the buyer wants to purchase. If this value is greater than the number available, the service will change this value to the number available. If this happens, a warning is returned.

Maximum: number available

Occurrence: Required

Output

HTTP response headers

{ /* RemoteShopcartResponse */ }
Output container/fieldTypeDescription
cartItemsarray of CartItemAn array of the items in the member's eBay cart.

Occurrence: Always

cartItems.cartItemIdstringThe identifier for the item being added to the cart. This is generated when the item is added to the cart.

Occurrence: Always

cartItems.cartItemSubtotalAmountThis is the subtotal of cost of a specific item in the cart. This does not include taxes, shipping costs, discounts, etc. It is price * quantity.

Occurrence: Conditional

cartItems.cartItemSubtotal.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Occurrence: Always

cartItems.cartItemSubtotal.valuestringThe dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

cartItems.imageImageThe primary image of the item. This is the image that appears on the eBay view item page for this item.

Occurrence: Always

cartItems.image.heightintegerReserved for future use.

Occurrence: Conditional

cartItems.image.imageUrlstringThe URL of the image.

Occurrence: Conditional

cartItems.image.widthintegerReserved for future use.

Occurrence: Conditional

cartItems.itemIdstringThe RESTful identifier of the item. This identifier is generated when the item was listed.

RESTful Item ID Format: v1|#|#
For example:
v1|272394640372|0
v1|162846450672|461882996982

Occurrence: Always

cartItems.itemWebUrlstringThe URL of the eBay view item page for the item.

Occurrence: Conditional

cartItems.pricePriceThe cost of the item.

Occurrence: Always

cartItems.price.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.

Occurrence: Conditional

cartItems.price.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

cartItems.price.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization was performed, this is the post-conversion currency of the amount in the value field.

Default: The currency of the user's country.

Occurrence: Always

cartItems.price.valuestringThe dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item. If currency conversion/localization was performed, this is the post-conversion amount.

Default: The currency of the user's country.

Occurrence: Always

cartItems.quantityintegerThe number of this item the buyer wants to purchase.

Occurrence: Conditional

cartItems.titlestringThe title of the item. This can be written by the seller or come from the eBay product catalog.

Occurrence: Always

cartSubtotalAmountThis is the cost of all the items in the member's eBay cart. This does not include taxes, shipping costs, discounts, etc. It is the sum of each item's price * quantity.

Occurrence: Always

cartSubtotal.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Occurrence: Always

cartSubtotal.valuestringThe dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

cartWebUrlstringThe URL of the member's eBay cart.

Occurrence: Always

unavailableCartItemsarray of CartItemAn array of items in the cart that are unavailable. This can be for a variety of reasons such as, when the listing has ended or the item is out of stock. Because a cart never expires, these items will remain in the cart until they are removed.

Occurrence: Conditional

unavailableCartItems.cartItemIdstringThe identifier for the item being added to the cart. This is generated when the item is added to the cart.

Occurrence: Always

unavailableCartItems.cartItemSubtotalAmountThis is the subtotal of cost of a specific item in the cart. This does not include taxes, shipping costs, discounts, etc. It is price * quantity.

Occurrence: Conditional

unavailableCartItems.cartItemSubtotal.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Occurrence: Always

unavailableCartItems.cartItemSubtotal.valuestringThe dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item.

Occurrence: Always

unavailableCartItems.imageImageThe primary image of the item. This is the image that appears on the eBay view item page for this item.

Occurrence: Always

unavailableCartItems.image.heightintegerReserved for future use.

Occurrence: Conditional

unavailableCartItems.image.imageUrlstringThe URL of the image.

Occurrence: Conditional

unavailableCartItems.image.widthintegerReserved for future use.

Occurrence: Conditional

unavailableCartItems.itemIdstringThe RESTful identifier of the item. This identifier is generated when the item was listed.

RESTful Item ID Format: v1|#|#
For example:
v1|272394640372|0
v1|162846450672|461882996982

Occurrence: Always

unavailableCartItems.itemWebUrlstringThe URL of the eBay view item page for the item.

Occurrence: Conditional

unavailableCartItems.pricePriceThe cost of the item.

Occurrence: Always

unavailableCartItems.price.convertedFromCurrencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency.

Occurrence: Conditional

unavailableCartItems.price.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

unavailableCartItems.price.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization was performed, this is the post-conversion currency of the amount in the value field.

Default: The currency of the user's country.

Occurrence: Always

unavailableCartItems.price.valuestringThe dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the eBay site offering the item. If currency conversion/localization was performed, this is the post-conversion amount.

Default: The currency of the user's country.

Occurrence: Always

unavailableCartItems.quantityintegerThe number of this item the buyer wants to purchase.

Occurrence: Conditional

unavailableCartItems.titlestringThe title of the item. This can be written by the seller or come from the eBay product catalog.

Occurrence: Always

warningsarray of ErrorDetailV3An array of warning messages. These type of errors do not prevent the call from executing but should be checked.

Occurrence: Always

warnings.categorystringThis string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Always

warnings.domainstringThe name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdintegerA unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Always

warnings.inputRefIdsarray of stringAn array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestringA detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestringA description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray of stringAn array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestringThis is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstringThe name of the subdomain in which the error or warning occurred.

Occurrence: NA

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200OK
204No Content
400Bad Request
403Insufficient permissions to fulfill the request
409Conflict
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
10000API_BROWSEAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
10001API_BROWSEREQUESTThe X-EBAY-C-MARKETPLACE-ID value is not supported. The supported values are: {supportedValues}.
10002API_BROWSEREQUESTInsufficient permissions to fulfill the request.
10007API_BROWSEREQUESTThe field: {field} is required. Add the field and resubmit the call.
10008API_BROWSEREQUESTThe item ID {itemId} is invalid.
10009API_BROWSEREQUESTThe quantity value is invalid. The quantity must be greater than 0.
10010API_BROWSEREQUESTThe item does not exist.
10011API_BROWSEBUSINESSThe item {itemId} is already in the shopping cart. To change the quantity of the item, use the updateQuantity call.
10016API_BROWSEBUSINESSYou have exceeded the maximum number of items in a cart, which is {MaxCartIems}. To add more items, either remove or purchase some of the items in the cart.
10017API_BROWSEBUSINESSThe item does not meet the cart criteria and cannot be added to the cart.
10018API_BROWSEBUSINESSThere is a limit on the quantity of this item that can be purchased. The quantity specified exceeds this limit.
10019API_BROWSEBUSINESSThe buyer is blocked from purchasing the item you are trying to add to the cart.
10021API_BROWSEBUSINESSThe item you are trying to add is not available in the quantity specified. Please adjust the quantity and try again.
10022API_BROWSEBUSINESSThe item you are trying to add is not available for purchase. This can be for several reason such as, the listing has ended or the item is out of stock.
10023API_BROWSEBUSINESSThe buyer is blocked from purchasing the item because the seller does not ship to the buyer's location.
10025API_BROWSEREQUESTThe header 'X-EBAY-C-MARKETPLACE-ID' is required. The valid Marketplaces are: {supportedValues}.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a Cart and Add an Item to the Cart

This call creates an eBay cart and adds one item to the cart.

Input

The inputs are itemId and quantity.
POST
https://api.ebay.com/buy/browse/v1/shopping_cart/add_item

Output

The output is the details of the items in the cart; cartItems containing the item information, and the quantity, price, and subtotal. It also returns the subtotal for all the items in the cart (cartSubtotal) and the URL of the cart (cartWebUrl).