GET/user_preferences
This method retrieves the seller's preferences for a specific eBay marketplace, such as combined payment preferences, same-day shipping cutoff time, excluded shipping locations, and opt-in status for Business Policies and Out-of-Stock control. The fieldgroups query parameter specifies the type of seller preferences to retrieve. If fieldgroups = ALL or the parameter is omitted, all the supported seller preferences are returned. To retrieve only specific preferences, include the fieldgroups parameter with one or more supported values, delimited by commas.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| fieldgroups | string | The fieldgroups query parameter specifies the type of seller preferences to retrieve. If fieldgroups= ALL or is omitted, all the supported seller preferences are returned. To retrieve specific seller preferences, include the fieldgroups parameter and specify one or more values, with each value delimited by a comma. For example, fieldgroups = SHIPPING_CARRIER_RATE,COMBINED_PAYMENT. The value can be ALL or any combination of the following (comma-separated):COMBINED_PAYMENT, DISPATCH_CUTOFF_TIME, EMAIL_SHIPMENT_TRACKING_NUMBER, END_OF_AUCTION_EMAIL, GLOBAL_SHIPPING_PROGRAM, GLOBAL_SHIPPING_PROGRAM_LISTING, ITEMS_AWAITING_PAYMENT, OUT_OF_STOCK_CONTROL SELLER_PROFILE, OVERRIDE_GSP_SERVICE_WITH_INTL_SERVICE, PICKUP_DROPOFF_SELLER, PURCHASE_REMINDER_EMAIL, REQUIRED_SHIP_PHONE_NUMBER, SELLER_EXCLUDE_SHIP_TO_LOCATION, SHIPPING_CARRIER_RATE Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| X-EBAY-C-MARKETPLACE-ID | string | This required header sets the eBay marketplace from which the seller's preferences are retrieved. See the MarketplaceIdEnum type for the full list of values. Occurrence: Required |
OAuth scope
This request requires an access token created with the client credentials 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/sell.account.readonly
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| combinedPaymentPreferences | CombinedPaymentPreferencesType | This container returns the combined payment preferences when the Occurrence: Conditional |
| combinedPaymentPreferences.combinedPaymentOption | CombinedPaymentOptionEnum | This enum type defines the available options for handling combined payments when a seller allows multiple line items from the same buyer to be paid for with a single payment. See Occurrence: Conditional |
| dispatchCutoffTimePreference | DispatchCutoffTimePreferencesType | This container is returned when the Occurrence: Conditional |
| dispatchCutoffTimePreference.cutoffTime | string | This field indicates the dispatch cut-off time in Zulu format ( Occurrence: Conditional |
| emailShipmentTrackingNumberPreference | boolean | This boolean field indicates whether or not the seller’s account is configured to automatically send an email to buyers with the shipment tracking number for an order. Occurrence: Conditional |
| endOfAuctionEmailPreferences | EndOfAuctionEmailPreferencesType | This container allows sellers to customize the email sent to buyers immediately after an auction listing is won. Occurrence: Conditional |
| endOfAuctionEmailPreferences.emailCustomized | boolean | This boolean field indicates whether or not the seller is using a customized email to send to winning bidders. Occurrence: Conditional |
| endOfAuctionEmailPreferences.logoCustomized | boolean | This boolean field indicates whether or not the seller is using a customized logo in the emails that are sent to winning bidders. Occurrence: Conditional |
| endOfAuctionEmailPreferences.logoType | EndOfAuctionLogoTypeEnum | This enum indicates the type of logo that is used in the email that is sent to winning bidders. See EndOfAuctionLogoTypeEnum type for descriptions of the different logo types. Occurrence: Conditional |
| endOfAuctionEmailPreferences.logoUrl | string | This field shows the URL path to a seller’s custom logo image that is being used in the email sent to winning bidders. This field is only returned if the seller is using a customized logo in emails. Occurrence: Conditional |
| endOfAuctionEmailPreferences.templateText | string | This field shows the body text that is being used if the seller is sending customized emails to winning bidders. The template text has a maximum limit of 1000 characters. Occurrence: Conditional |
| endOfAuctionEmailPreferences.textCustomized | boolean | This boolean field indicates whether or not the seller is using customized text in the emails that are sent to winning bidders. Occurrence: Conditional |
| globalShippingProgramListingPreference | boolean | This boolean field indicates whether or not the seller’s new listings on the eBay marketplace will automatically use the Global Shipping Program for international shipping. This field is returned when the Occurrence: Conditional |
| itemsAwaitingPaymentPreferences | GetItemsAwaitingPaymentPreferencesType | This container shows the seller’s preferences for automatically handling unpaid line items. Occurrence: Conditional |
| itemsAwaitingPaymentPreferences.autoRelist | boolean | This boolean indicates if the item should be automatically relisted. Occurrence: Conditional |
| itemsAwaitingPaymentPreferences.delayBeforeCancellingCommitment | integer | This integer indicates the delay in days before cancelling the buyer's commitment. Occurrence: Conditional |
| itemsAwaitingPaymentPreferences.excludedUsers | array of string | This string returns the list of sellers excluded from unpaid item assistance. Occurrence: Conditional |
| itemsAwaitingPaymentPreferences.optInStatus | boolean | This boolean indicates if the unpaid item assistance is opted in. Occurrence: Conditional |
| offerGlobalShippingProgramPreference | boolean | This boolean field indicates whether or not the seller is opted into the Global Shipping Program on the eBay marketplace. Note: The Global Shipping Program is only available for the eBay UK marketplace. Occurrence: Conditional |
| outOfStockControlPreference | boolean | This boolean field indicates whether or not the seller is opted into the Out-of-Stock feature. With this feature, a multiple quantity fixed price listing that runs out of stock will be hidden from eBay search but kept alive. Once the sellers add quantity to the listing, the listing will become active and available again. Occurrence: Conditional |
| overrideGspServiceWithIntlServicePreference | boolean | This boolean field indicates whether or not the seller specifies an international shipping service to a particular country for a given listing, the specified service will take precedence and be the listing's default international shipping option for buyers in that country, rather than the Global Shipping Program. Note: The Global Shipping Program is only available for the eBay UK marketplace. Occurrence: Conditional |
| pickupDropoffSellerPreference | boolean | This boolean field indicates whether or not the seller is opted into the Click & Collect feature. Note: The Click & Collect feature is only available on the eBay UK, Australia, and Germany marketplaces. Occurrence: Conditional |
| purchaseReminderEmailPreferences | boolean | This boolean field indicates whether or not the seller’s account is configured to have eBay send occasional purchase reminder emails for unpaid line items. Occurrence: Conditional |
| requiredShipPhoneNumberPreference | boolean | This boolean field indicates whether or not the buyer is required to provide a shipping phone number during checkout. Occurrence: Conditional |
| sellerExcludeShipToLocationPreferences | SellerExcludeShipToLocationPreferencesType | This container shows the list of locations that the seller does not ship to. This list of shipping locations can only be updated in My eBay through Shipping Preferences and not with the Occurrence: Conditional |
| sellerExcludeShipToLocationPreferences.excludeShipToLocations | array of string | This array shows the list of locations that the seller does not ship to. Excluded locations may include continents and large geographical areas. For example, 'Middle East', individual countries represented by two-letter codes, or special locations within a country such as 'Alaska/Hawaii' or 'PO Box'. Occurrence: Conditional |
| sellerProfilePreferences | SellerProfilePreferencesType | This container is returned when the Occurrence: Conditional |
| sellerProfilePreferences.sellerProfileOptedIn | boolean | This boolean indicates whether the seller has opted in to seller profiles. Occurrence: Conditional |
| shippingCarrierRatePreferences | ShippingCarrierRatePreferencesType | This container indicates the FedEx, UPS, and US Post Office shipping rate types that are available to the seller. This container is returned when the Occurrence: Conditional |
| shippingCarrierRatePreferences.fedexRateOption | FedexRateOptionEnum | This enum is included if the seller wishes to add or modify the FedEx shipping carrier rate. Note: This preference is only applicable to the eBay US marketplace. Occurrence: Conditional |
| shippingCarrierRatePreferences.upsRateOption | UPSRateOptionEnum | This enum is included if the seller wishes to add or modify the UPS shipping carrier rate. Note: This preference is only applicable to the eBay US marketplace. Occurrence: Conditional |
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.
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 396500 | API_ACCOUNT | APPLICATION | Internal Server Error. Please try again later or contact Developer Technical Support. |
| 396502 | API_ACCOUNT | REQUEST | The specified field groups are invalid. Error Details - {errorDetails} |
Warnings
This call has no warnings.
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: Get user preferences
This method retrieves the seller's preferences for a specific eBay marketplace, specified through the X-EBAY-C-MARKETPLACE-ID HTTP header (see HTTP request header).
Input
The input for this sample is the fieldgroups query parameter which is set to ALL.
GEThttps://api.ebay.com/sell/account/v2/user_preferences?fieldgroups=ALL
Output
If the call is successful, all of the supported seller preferences are returned in the output. These include available details as defined in the response payload.