Skip to main content

PATCH/user_preferences

This method is used to modify one or more preferences for a seller on a specific marketplace. The preferences that can be modified include combined payment preferences, same-day shipping cutoff time, and opt-in status for Business Policies and Out-of-stock control. This is a PATCH operation, so you only need to include the fields that correspond to the preferences/settings that you are changing.

Input

Resource URI

PATCH https://api.ebay.com/sell/account/v2/user_preferences

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

This method has no URI parameters.

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.

HeaderTypeDescription
X-EBAY-C-MARKETPLACE-IDstringThis required header sets the eBay marketplace, which the seller has specified. See the MarketplaceIdEnum type for the full list of values.

Occurrence: Required

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/sell.account

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
combinedPaymentPreferencesCombinedPaymentPreferencesType

This container is included if the seller wishes to allow combined invoices if the buyer has multiple unpaid orders from the same seller.

Occurrence: Optional

combinedPaymentPreferences.combinedPaymentOptionCombinedPaymentOptionEnum

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 CombinedPaymentOptionEnum for a description of each value.

Occurrence: Conditional

dispatchCutoffTimePreferenceDispatchCutoffTimePreferencesType

This container is included if the seller wishes to set or modify the order cut-off time for same-day shipping.

Occurrence: Optional

dispatchCutoffTimePreference.cutoffTimestring

This field indicates the dispatch cut-off time in Zulu format (HH:mm:ss.SSSZ) - 24-hour format with milliseconds and Z timezone indicator.
Note: Despite the Z that is returned in the timestamp, the cut-off time is actually based on the default timezone of the eBay marketplace for the seller.
Note: If an eBay listing supports same-day shipping, and an order is paid for before the cut-off time, the seller is expected to ship the order out that same business day.

Occurrence: Conditional

emailShipmentTrackingNumberPreferenceboolean

This field is included if the seller wishes to enable or disable the setting that will automatically email the buyer with the tracking number when it becomes available.

Occurrence: Optional

endOfAuctionEmailPreferencesEndOfAuctionEmailPreferencesType

This container is included if the seller wishes to change one or more of the end of auction email preferences.

Occurrence: Optional

endOfAuctionEmailPreferences.emailCustomizedboolean

This boolean field indicates whether or not the seller is using a customized email to send to winning bidders.

Occurrence: Optional

endOfAuctionEmailPreferences.logoCustomizedboolean

This boolean field indicates whether or not the seller is using a customized logo in the emails that are sent to winning bidders.

Occurrence: Optional

endOfAuctionEmailPreferences.logoTypeEndOfAuctionLogoTypeEnum

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: Optional

endOfAuctionEmailPreferences.logoUrlstring

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: Optional

endOfAuctionEmailPreferences.templateTextstring

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: Optional

endOfAuctionEmailPreferences.textCustomizedboolean

This boolean field indicates whether or not the seller is using customized text in the emails that are sent to winning bidders.

Occurrence: Optional

globalShippingProgramListingPreferenceboolean

This boolean field is included if the seller wishes to toggle the setting that controls whether or not the seller’s new listings on the eBay UK marketplace will automatically use the Global Shipping Program for international shipping.
Note: The Global Shipping Program is only available for the eBay UK marketplace, and the seller must be opted into the program, that is offerGlobalShippingProgramPreference = true

Occurrence: Optional

itemsAwaitingPaymentPreferencesSetItemsAwaitingPaymentPreferencesType

This container is included if the seller wishes to change one or more of the items awaiting payment preferences.

Occurrence: Optional

itemsAwaitingPaymentPreferences.autoRelistboolean

This boolean field is included if the seller wishes to toggle the setting that controls whether or not the line item should be automatically relisted when cancelled. For this field to be set to true, the optInStatus field should also be true.
Note: If the line item was part of an auction listing or a single-quantity fixed price listing, a new listing will actually be created. If the line item was part of a multiple-quantity fixed price listing, eBay will only adjust the quantity based on the cancelled line item’s quantity.

Occurrence: Optional

itemsAwaitingPaymentPreferences.delayBeforeCancellingCommitmentinteger

This integer field is included if the seller wishes to set or change the number of business days without payment that must elapse before the line item is cancelled. This is a required field if the optInStatus field is true.
Note: The supported integer values (representing business days) varies by eBay marketplace.

Occurrence: Optional

itemsAwaitingPaymentPreferences.excludedUsersarray of string

This array is used if the seller wishes to exclude one or more eBay users from the unpaid item assistance mechanism. The seller would need to manually cancel any unpaid line items for all users on this list. This array will not be returned if there are no users on the excluded users list.
Note: The eBay public username is used for each excluded user, and a comma is used to delimit each user in the array.

Occurrence: Optional

itemsAwaitingPaymentPreferences.optInStatusboolean

This boolean field is included if the seller wishes to toggle the setting that controls whether or not the seller is opted into the unpaid item assistance mechanism. If the seller is not opted in, no other fields under itemsAwaitingPaymentPreferences are applicable.

Occurrence: Optional

itemsAwaitingPaymentPreferences.removeAllExcludedUsersboolean

This boolean field is included and set to true if the seller wishes to remove all eBay users from the current excluded users list. If this field is included and set to true, the excludedUsers array should not be included.

Occurrence: Optional

outOfStockControlPreferenceboolean

This boolean field is included if the seller wishes to toggle the setting that controls 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: Optional

purchaseReminderEmailPreferencesboolean

This boolean field is included if the seller wishes to toggle the setting that controls whether or not the buyer is expected to provide a shipping phone number upon checkout. Some shipping carriers require the receiver's phone number.

Occurrence: Optional

requiredShipPhoneNumberPreferenceboolean

This boolean indicates whether the seller wishes to require phone numbers for shipping or not.

Occurrence: Optional

shippingCarrierRatePreferencesShippingCarrierRatePreferencesType

This container is included if the seller wishes to add or modify a FedEx, UPS, and/or US Post Office shipping rate type that is available to the seller.
Note: This container is only applicable to the eBay US marketplace.

Occurrence: Optional

shippingCarrierRatePreferences.fedexRateOptionFedexRateOptionEnum

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: Optional

shippingCarrierRatePreferences.upsRateOptionUPSRateOptionEnum

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: Optional

Output

HTTP response headers

This call has no response headers.

Response payload

This call has no payload.

Response fields

This call has no field definitions.

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
204No Content
400Bad Request
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
396500API_ACCOUNTAPPLICATIONInternal Server Error. Please try again later or contact Developer Technical Support.
396510API_ACCOUNTREQUESTDispatch cutoff time format is invalid. Expected format: HH:mm:ss.SSSZ
396511API_ACCOUNTREQUESTThe optInStatus field is included and set to 'false', no other itemsAwaitingPaymentPreferences fields can be used.
396512API_ACCOUNTREQUESTThe removeAllExcludedUsers field is included and set to 'true', the excludedUsers array cannot be used.
396513API_ACCOUNTREQUESTThe delayBeforeCancellingCommitment value is invalid. See the documentation for valid values.
396514API_ACCOUNTREQUESTThe seller's account has reached the maximum number of users ({maxNo}) that can be added to the Excluded Users list.
396515API_ACCOUNTREQUESTThe number of users included in the excludedUsers array exceeds the daily maximum threshold. Please remove one or more users and try again.
396516API_ACCOUNTREQUESTOne or more invalid user IDs included in the excludedUsers array.
396517API_ACCOUNTREQUESTInvalid value specified for combinedPaymentOption field. See documentation for valid values.
396518API_ACCOUNTREQUESTCustomization of End of Auction email is not supported for this marketplace.
396519API_ACCOUNTREQUESTThe provided text in the templateText field exceeds the maximum allowed number of characters (1000).
396520API_ACCOUNTREQUESTThe provided text in the templateText field contains vulgar language or prohibited HTML content.
396521API_ACCOUNTREQUESTLogo URL is required but not provided.
396522API_ACCOUNTREQUESTThe format of the logo image in the provided logoUrl field is not supported. See documentation for supported image formats.
396523API_ACCOUNTREQUESTLogo URL exceeds maximum allowed length of 1024 characters.
396524API_ACCOUNTREQUESTThe marketplace does not support the Global Shipping Program and/or the user is not enrolled in the program.
396525API_ACCOUNTREQUESTInvalid value specified for upsRateOption field. See documentation for valid values.
396526API_ACCOUNTREQUESTInvalid value specified for fedexRateOption field. See documentation for valid values.
396528API_ACCOUNTREQUESTThe textCustomized field is set to ‘true’, so the templateText field must also be included.
396529API_ACCOUNTREQUESTThe textCustomized field is set to ‘false’, so the templateText field is not applicable.
396530API_ACCOUNTREQUESTInvalid value specified for logoType field. See documentation for valid values.
396531API_ACCOUNTREQUESTThe logoType field is not set to CUSTOMIZED, so the logoUrl field is not applicable.

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: Set user preferences

This method sets 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 contains fields from the request payload and sets (or updates) these values for the seller for the eBay marketplace specified in the HTTP request header.

PATCHhttps://api.ebay.com/sell/account/v2/user_preferences

Output

If the call succeeds, it returns HTTP status 204 No Content, and the seller's preferences for the specified marketplace are updated.