--- title: Account API v2 description: "Use the Account v2 API to retrieve and manage seller account settings for shipping rate tables, split payouts, combined shipping rules, and seller preferences. The rate\\_table resource lets sellers retrieve shipping rate table details and update shipping costs for specific shipping rate tables. The payout\\_settings resource lets eligible sellers in mainland China retrieve payout instruments and configure split-payout percentages between two payout instruments. The combined\\_shipping\\_rules resource lets sellers create, retrieve, and update combined shipping rules, including calculated, flat-rate, promotional, and combined-payment settings. The user\\_preferences resource lets sellers retrieve and update marketplace-specific preferences, such as combined payment preferences, same-day shipping cutoff time, shipping carrier rate preferences, unpaid item preferences, and out-of-stock control." api_version: 1.0 api_name: account_api_v2 api_type: REST api_group: sell/account_api_v2 source_url: html: https://developer.ebay.com/develop/api/sell/account_api_v2 md: https://developer.ebay.com/develop/api/sell/account_api_v2.md --- # Account API v2 API Use the Account v2 API to retrieve and manage seller account settings for shipping rate tables, split payouts, combined shipping rules, and seller preferences. The rate\_table resource lets sellers retrieve shipping rate table details and update shipping costs for specific shipping rate tables. The payout\_settings resource lets eligible sellers in mainland China retrieve payout instruments and configure split-payout percentages between two payout instruments. The combined\_shipping\_rules resource lets sellers create, retrieve, and update combined shipping rules, including calculated, flat-rate, promotional, and combined-payment settings. The user\_preferences resource lets sellers retrieve and update marketplace-specific preferences, such as combined payment preferences, same-day shipping cutoff time, shipping carrier rate preferences, unpaid item preferences, and out-of-stock control. ## API Methods The following API methods are available: ### getRateTable #### GET /rate_table/{rate_table_id} **Description:** This method retrieves an existing rate table identified by the **rate\_table\_id** path parameter. Shipping rate tables are currently supported by the following marketplaces: United States, Canada, United Kingdom, Germany, Australia, France, Italy, and Spain. A successful call returns detailed information for the specified shipping rate table. **Parameters:** - **rate_table_id** (string) *required* - This path parameter is the unique identifier for the shipping rate table to retrieve. Use the [getRateTables](/develop/api/sell/account_api#sell-account_api-rate_table-getratetables) method of the [Account API v1](/develop/api/sell/account_api) to retrieve rate table IDs. ### updateShippingCost #### POST /rate_table/{rate_table_id}/update_shipping_cost **Description:** This method allows sellers to update **shippingCost** and/or **additionalCost** information for an existing shipping rate table identified by the **rate\_table\_id** path parameter. A successful call returns an HTTP status code of **204 No Content**. **Parameters:** - **rate_table_id** (string) *required* - This path parameter is the unique identifier for the shipping rate table for which shipping costs will be updated. Use the [getRateTables](/develop/api/sell/account_api#sell-account_api-rate_table-getratetables) method of the [Account API v1](/develop/api/sell/account_api) to retrieve rate table IDs. - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. For more information, refer to [HTTP request headers](/develop/guides-v2/using-ebay-restful-apis#request-components). ### getPayoutSettings #### GET /payout_settings **Description:** **Important!** Split-payout functionality is **only** available to mainland China sellers, who can split payouts between their Payoneer account and bank account. Card payouts are not currently available for sellers in mainland China. This method returns details on two payment instruments defined on a seller's account, including the ID, type, status, nickname, last four digits of the account number, and payout percentage for the instruments. Using the **instrumentId** returned with this method, sellers can makes changes to the payout split of the instruments with the **updatePayoutPercentage** method. Note that the **instrumentStatus** of a payment instrument, also returned using this method, must be `ACTIVE` in order to do split payouts on that payment instrument. ### updatePayoutPercentage #### POST /payout_settings/update_percentage **Description:** **Important!** Split-payout functionality is **only** available to mainland China sellers, who can split payouts between their Payoneer account and bank account. Card payouts are not currently available for sellers in mainland China. This method allows sellers in mainland China to configure the split-payout percentage for two payout instruments available for seller payouts. For example, a seller can split payouts to have 70% of the payout go to a bank account and 30% go to a Payoneer account. **Note:** The split-payout percentage **must** always add up to 100%. If the values do not equal 100, the call will fail. Instruments cannot be added/removed using Finance and Account APIs. Users can specify the payout instruments being updated by using the **instrumentId** associated with each payment instrument in the request payload. This value is returned by using the **getPayoutSettings** method. Users can specify the percentage of the payout allocated to each instrument using the **payoutPercentage** request field. This value must be a whole number and cannot exceed 100. For more details on configuring split-payout percentages, see [Mainland China Split Payout Playbook.](/api-docs/split-payout/playbook.html) **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. For more information, refer to [HTTP request headers](/develop/guides-v2/using-ebay-restful-apis#request-components). ### createCalculatedShippingRules #### POST /combined_shipping_rules/create_calculated_shipping_rules **Description:** This method creates or registers calculated shipping rules that determine combined shipping costs based on weight, item count, or cost parameters for an authenticated seller. This shipping rule will apply to eBay listings that use the calculated shipping model. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### createFlatShippingRules #### POST /combined_shipping_rules/create_flat_shipping_rules **Description:** This method is used to create fixed-rate (flat) shipping rules that apply standard combined shipping costs for a seller’s listings. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### createPromotionalShippingRule #### POST /combined_shipping_rules/create_promotional_shipping_rule **Description:** This method defines promotional shipping rules such as discounts or free-shipping thresholds, configurable by marketplace for the seller. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### getCombinedShippingRules #### GET /combined_shipping_rules **Description:** This method retrieves all existing combined shipping rule configurations defined by the authenticated seller, including calculated, flat, and promotional types. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### updateCalculatedShippingRules #### POST /combined_shipping_rules/update_calculated_shipping_rules **Description:** This method updates previously defined calculated shipping rules to modify discount percentages, weight offsets, or amount parameters for the seller. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### updateCombinedPayments #### POST /combined_shipping_rules/update_combined_payments **Description:** This method configures or modifies combined payment settings that determine how unpaid orders can be merged for a single invoice within a defined duration for the seller. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### updateFlatShippingRules #### POST /combined_shipping_rules/update_flat_shipping_rules **Description:** This method updates existing shipping rules. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### updatePromotionalShippingRule #### POST /combined_shipping_rules/update_promotional_shipping_rule **Description:** This method updates an existing promotional shipping rule to adjust discount thresholds, eligibility criteria, or duration for the seller. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### getUserPreferences #### GET /user_preferences **Description:** 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. **Parameters:** - **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` - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. ### setUserPreferences #### PATCH /user_preferences **Description:** 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. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This required header sets the eBay marketplace where the request is processed. For the full list of eBay marketplace values, see the [MarketplaceIdEnum](/develop/api/sell/account_api_v2#sell-account_api_v2-rate_table-getratetable.ratetabledetails.marketplaceid) type. - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. For more information, refer to [HTTP request headers](/develop/guides-v2/using-ebay-restful-apis#request-components). ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 394001 - API_ACCOUNT **Description:** The specified rate table ID is invalid. Please input a valid rate table ID. The getRateTables method can be used to retrieve valid rate table IDs #### 394004 - API_ACCOUNT **Description:** Please specify at least one shipping rate entry to add/update through the rates array. #### 394007 - API_ACCOUNT **Description:** Please specify the rateId value for one or more shipping rate entries being updated. #### 394008 - API_ACCOUNT **Description:** The shippingCost containers are missing for one or more shipping rate entries. Please provide the shipping cost values for the shipping rate entries being updated. #### 394009 - API_ACCOUNT **Description:** The specified shipping cost currency does not match the currency used for the marketplace. #### 394011 - API_ACCOUNT **Description:** The additional cost containers are missing for one or more shipping rate entries for the WEIGHT/SURCHARGE rate table. Please provide these values for the additional rate entries being added/updated. #### 394012 - API_ACCOUNT **Description:** The specified additional cost currency does not match the currency used for the marketplace. #### 394015 - API_ACCOUNT **Description:** The number of rate entries must be less than or equal to the existing data. #### 394025 - API_ACCOUNT **Description:** The shipping cost value is invalid. #### 394026 - API_ACCOUNT **Description:** The additional cost value is invalid. #### 394035 - API_ACCOUNT **Description:** The shipping cost is not supported in surcharge calculation type. #### 394036 - API_ACCOUNT **Description:** Additional costs are not applicable for shipping rate tables based on shipping item. Please remove the additional cost container. #### 394041 - API_ACCOUNT **Description:** The rateId of rates is repeated. #### 394100 - API_ACCOUNT **Description:** The seller is not eligible to set split-payout percentage. #### 394101 - API_ACCOUNT **Description:** Missing instrumentId in request. #### 394102 - API_ACCOUNT **Description:** Missing payoutPercentage in request. #### 394103 - API_ACCOUNT **Description:** The 'payoutPercentage' {payoutPercentage} is not valid. The payout percentage should be an integer value. Minimum value: {0}, Maximum value: {100}. #### 394104 - API_ACCOUNT **Description:** Duplicate instrumentId in request. #### 394105 - API_ACCOUNT **Description:** Sum up of 'payoutPercentage' in request must be equal to 100, current value {payoutPercentage}. #### 394106 - API_ACCOUNT **Description:** Instrument 'instrumentId' {instrumentId} not found. #### 394107 - API_ACCOUNT **Description:** Instrument 'instrumentId' {instrumentId} missing in request. #### 396000 - API_ACCOUNT **Description:** Invalid or missing 'currency'. #### 396002 - API_ACCOUNT **Description:** Invalid or missing 'combinedShippingRuleType'. #### 396003 - API_ACCOUNT **Description:** Combined shipping rule names must be unique. Rule names cannot match existing rules in the system or be duplicated within the request. #### 396004 - API_ACCOUNT **Description:** Invalid or missing 'combinedShippingRules' data. Please verify all required fields are provided with valid values. #### 396005 - API_ACCOUNT **Description:** Invalid or missing 'combinedShippingRuleName'. #### 396006 - API_ACCOUNT **Description:** Invalid or missing 'eachAdditionalAmount'. #### 396007 - API_ACCOUNT **Description:** Invalid or missing 'combinedDuration'. #### 396008 - API_ACCOUNT **Description:** Invalid or missing 'eachAdditionalAmountOffShippingCost'. #### 396009 - API_ACCOUNT **Description:** Invalid or missing 'eachAdditionalPercentOffShippingCost'. #### 396010 - API_ACCOUNT **Description:** For create operation, 'combinedShippingRuleId' is not allowed. #### 396012 - API_ACCOUNT **Description:** Invalid or missing 'combinedShippingRuleType' in 'calculatedHandlingRule'. #### 396013 - API_ACCOUNT **Description:** Invalid or missing amount data in 'calculatedHandlingRule'. #### 396019 - API_ACCOUNT **Description:** Invalid or missing 'eachAdditionalPercentOffShippingCost'. #### 396021 - API_ACCOUNT **Description:** Invalid or missing 'weightOffTotalWeight'. #### 396023 - API_ACCOUNT **Description:** The specified marketplace ID was not found. #### 396025 - API_ACCOUNT **Description:** Missing 'calculatedShippingRule'. #### 396024 - API_ACCOUNT **Description:** Missing 'flatShippingRule'. #### 396001 - API_ACCOUNT **Description:** Missing 'promotionalShippingRule'. #### 396014 - API_ACCOUNT **Description:** The specified combined shipping rule data does not match any existing rules or the operation is not supported for this rule type. #### 396017 - API_ACCOUNT **Description:** Invalid or missing 'shippingCost'. #### 396018 - API_ACCOUNT **Description:** Invalid or missing 'orderAmount'. #### 396020 - API_ACCOUNT **Description:** Invalid or missing 'itemCount'. #### 396011 - API_ACCOUNT **Description:** Invalid or missing 'combinedShippingRuleId'. #### 396016 - API_ACCOUNT **Description:** The provided 'combinedShippingRuleName' differs from the existing combined shipping rule name. The existing name will be preserved. #### 396022 - API_ACCOUNT **Description:** Duplicate 'combinedShippingRuleId' found. Each rule id must be unique within the request. #### 396026 - API_ACCOUNT **Description:** Missing 'calculatedShippingRule' or 'calculatedHandlingRule'. #### 396502 - API_ACCOUNT **Description:** The specified field groups are invalid. Error Details - {errorDetails} #### 396510 - API_ACCOUNT **Description:** Dispatch cutoff time format is invalid. Expected format: HH:mm:ss.SSSZ #### 396511 - API_ACCOUNT **Description:** The optInStatus field is included and set to 'false', no other itemsAwaitingPaymentPreferences fields can be used. #### 396512 - API_ACCOUNT **Description:** The removeAllExcludedUsers field is included and set to 'true', the excludedUsers array cannot be used. #### 396513 - API_ACCOUNT **Description:** The delayBeforeCancellingCommitment value is invalid. See the documentation for valid values. #### 396514 - API_ACCOUNT **Description:** The seller's account has reached the maximum number of users ({maxNo}) that can be added to the Excluded Users list. #### 396515 - API_ACCOUNT **Description:** 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 **Description:** One or more invalid user IDs included in the excludedUsers array. #### 396517 - API_ACCOUNT **Description:** Invalid value specified for combinedPaymentOption field. See documentation for valid values. #### 396518 - API_ACCOUNT **Description:** Customization of End of Auction email is not supported for this marketplace. #### 396519 - API_ACCOUNT **Description:** The provided text in the templateText field exceeds the maximum allowed number of characters (1000). #### 396520 - API_ACCOUNT **Description:** The provided text in the templateText field contains vulgar language or prohibited HTML content. #### 396521 - API_ACCOUNT **Description:** Logo URL is required but not provided. #### 396522 - API_ACCOUNT **Description:** The format of the logo image in the provided logoUrl field is not supported. See documentation for supported image formats. #### 396523 - API_ACCOUNT **Description:** Logo URL exceeds maximum allowed length of 1024 characters. #### 396524 - API_ACCOUNT **Description:** The marketplace does not support the Global Shipping Program and/or the user is not enrolled in the program. #### 396525 - API_ACCOUNT **Description:** Invalid value specified for upsRateOption field. See documentation for valid values. #### 396526 - API_ACCOUNT **Description:** Invalid value specified for fedexRateOption field. See documentation for valid values. #### 396528 - API_ACCOUNT **Description:** The textCustomized field is set to ‘true’, so the templateText field must also be included. #### 396529 - API_ACCOUNT **Description:** The textCustomized field is set to ‘false’, so the templateText field is not applicable. #### 396530 - API_ACCOUNT **Description:** Invalid value specified for logoType field. See documentation for valid values. #### 396531 - API_ACCOUNT **Description:** The logoType field is not set to CUSTOMIZED, so the logoUrl field is not applicable. ### APPLICATION Errors #### 395000 - API_ACCOUNT **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. #### 395100 - API_ACCOUNT **Description:** There was an internal error, please try again after sometime. #### 396500 - API_ACCOUNT **Description:** Internal Server Error. Please try again later or contact Developer Technical Support. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-08T04:33:32.029Z*