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
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.
| Header | Type | Description |
|---|---|---|
| X-EBAY-C-MARKETPLACE-ID | string | This 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 clipboardRequest fields
| Input container/field | Type | Description |
|---|---|---|
| combinedPaymentPreferences | CombinedPaymentPreferencesType | 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.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 included if the seller wishes to set or modify the order cut-off time for same-day shipping. Occurrence: Optional |
| dispatchCutoffTimePreference.cutoffTime | string | This field indicates the dispatch cut-off time in Zulu format ( Occurrence: Conditional |
| emailShipmentTrackingNumberPreference | boolean | 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 |
| endOfAuctionEmailPreferences | EndOfAuctionEmailPreferencesType | This container is included if the seller wishes to change one or more of the end of auction email preferences. Occurrence: Optional |
| endOfAuctionEmailPreferences.emailCustomized | boolean | This boolean field indicates whether or not the seller is using a customized email to send to winning bidders. Occurrence: Optional |
| 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: Optional |
| 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: Optional |
| 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: Optional |
| 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: Optional |
| 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: Optional |
| globalShippingProgramListingPreference | boolean | 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 Occurrence: Optional |
| itemsAwaitingPaymentPreferences | SetItemsAwaitingPaymentPreferencesType | This container is included if the seller wishes to change one or more of the items awaiting payment preferences. Occurrence: Optional |
| itemsAwaitingPaymentPreferences.autoRelist | boolean | 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 Occurrence: Optional |
| itemsAwaitingPaymentPreferences.delayBeforeCancellingCommitment | integer | 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 Occurrence: Optional |
| itemsAwaitingPaymentPreferences.excludedUsers | array 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.optInStatus | boolean | 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 Occurrence: Optional |
| itemsAwaitingPaymentPreferences.removeAllExcludedUsers | boolean | This boolean field is included and set to Occurrence: Optional |
| outOfStockControlPreference | boolean | 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 |
| purchaseReminderEmailPreferences | boolean | 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 |
| requiredShipPhoneNumberPreference | boolean | This boolean indicates whether the seller wishes to require phone numbers for shipping or not. Occurrence: Optional |
| shippingCarrierRatePreferences | ShippingCarrierRatePreferencesType | 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.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: Optional |
| 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: 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.
| Status | Meaning |
|---|---|
| 204 | No Content |
| 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. |
| 396510 | API_ACCOUNT | REQUEST | Dispatch cutoff time format is invalid. Expected format: HH:mm:ss.SSSZ |
| 396511 | API_ACCOUNT | REQUEST | The optInStatus field is included and set to 'false', no other itemsAwaitingPaymentPreferences fields can be used. |
| 396512 | API_ACCOUNT | REQUEST | The removeAllExcludedUsers field is included and set to 'true', the excludedUsers array cannot be used. |
| 396513 | API_ACCOUNT | REQUEST | The delayBeforeCancellingCommitment value is invalid. See the documentation for valid values. |
| 396514 | API_ACCOUNT | REQUEST | The seller's account has reached the maximum number of users ({maxNo}) that can be added to the Excluded Users list. |
| 396515 | API_ACCOUNT | REQUEST | The number of users included in the excludedUsers array exceeds the daily maximum threshold. Please remove one or more users and try again. |
| 396516 | API_ACCOUNT | REQUEST | One or more invalid user IDs included in the excludedUsers array. |
| 396517 | API_ACCOUNT | REQUEST | Invalid value specified for combinedPaymentOption field. See documentation for valid values. |
| 396518 | API_ACCOUNT | REQUEST | Customization of End of Auction email is not supported for this marketplace. |
| 396519 | API_ACCOUNT | REQUEST | The provided text in the templateText field exceeds the maximum allowed number of characters (1000). |
| 396520 | API_ACCOUNT | REQUEST | The provided text in the templateText field contains vulgar language or prohibited HTML content. |
| 396521 | API_ACCOUNT | REQUEST | Logo URL is required but not provided. |
| 396522 | API_ACCOUNT | REQUEST | The format of the logo image in the provided logoUrl field is not supported. See documentation for supported image formats. |
| 396523 | API_ACCOUNT | REQUEST | Logo URL exceeds maximum allowed length of 1024 characters. |
| 396524 | API_ACCOUNT | REQUEST | The marketplace does not support the Global Shipping Program and/or the user is not enrolled in the program. |
| 396525 | API_ACCOUNT | REQUEST | Invalid value specified for upsRateOption field. See documentation for valid values. |
| 396526 | API_ACCOUNT | REQUEST | Invalid value specified for fedexRateOption field. See documentation for valid values. |
| 396528 | API_ACCOUNT | REQUEST | The textCustomized field is set to ‘true’, so the templateText field must also be included. |
| 396529 | API_ACCOUNT | REQUEST | The textCustomized field is set to ‘false’, so the templateText field is not applicable. |
| 396530 | API_ACCOUNT | REQUEST | Invalid value specified for logoType field. See documentation for valid values. |
| 396531 | API_ACCOUNT | REQUEST | The 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.