{ "openapi": "3.0.0", "info": { "title": "Account v2 API", "description": "This API allows sellers to retrieve and manage their custom shipping rate tables. In addition, this API also provides sellers in mainland China methods to configure split-payouts between two separate payment instruments.", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "2.2.0" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/sell/account/v2" } } } ], "paths": { "/rate_table/{rate_table_id}": { "get": { "tags": [ "rate_table" ], "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.", "operationId": "getRateTable", "parameters": [ { "name": "rate_table_id", "in": "path", "description": "This path parameter is the unique identifier for the shipping rate table to retrieve.

Use the getRateTables method of the Account API v1 to retrieve rate table IDs.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateTableDetails" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "394001": { "domain": "API_ACCOUNT", "category": "REQUEST", "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" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account", "https://api.ebay.com/oauth/api_scope/sell.account.readonly" ] } ] } }, "/rate_table/{rate_table_id}/update_shipping_cost": { "post": { "tags": [ "rate_table" ], "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.", "operationId": "updateShippingCost", "parameters": [ { "name": "rate_table_id", "in": "path", "description": "This path parameter is the unique identifier for the shipping rate table for which shipping costs will be updated.

Use the getRateTables method of the Account API v1 to retrieve rate table IDs.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "This header indicates the format of the request body provided by the client. It's value should be set to application/json.

For more information, refer to HTTP request headers.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request to update the shipping costs for the identified shipping rate table.", "content": { "application/json": { "schema": { "description": "Request to update the shipping costs for the identified shipping rate table.", "$ref": "#/components/schemas/RateTableUpdate" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "394001": { "domain": "API_ACCOUNT", "category": "REQUEST", "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": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Please specify at least one shipping rate entry to add/update through the rates array." }, "394007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Please specify the rateId value for one or more shipping rate entries being updated." }, "394008": { "domain": "API_ACCOUNT", "category": "REQUEST", "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": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified shipping cost currency does not match the currency used for the marketplace." }, "394011": { "domain": "API_ACCOUNT", "category": "REQUEST", "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": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified additional cost currency does not match the currency used for the marketplace." }, "394015": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The number of rate entries must be less than or equal to the existing data." }, "394025": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The shipping cost value is invalid." }, "394026": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The additional cost value is invalid." }, "394035": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The shipping cost is not supported in surcharge calculation type." }, "394036": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Additional costs are not applicable for shipping rate tables based on shipping item. Please remove the additional cost container." }, "394041": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The rateId of rates is repeated." } } } }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/payout_settings": { "get": { "tags": [ "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.", "operationId": "getPayoutSettings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutSettingsResponse" } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.finances" ] } ] } }, "/payout_settings/update_percentage": { "post": { "tags": [ "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 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. ", "operationId": "updatePayoutPercentage", "parameters": [ { "name": "Content-Type", "in": "header", "description": "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.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePayoutPercentageRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "394100": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The seller is not eligible to set split-payout percentage." }, "394101": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing instrumentId in request." }, "394102": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing payoutPercentage in request." }, "394103": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The 'payoutPercentage' {payoutPercentage} is not valid. The payout percentage should be an integer value. Minimum value: {0}, Maximum value: {100}." }, "394104": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Duplicate instrumentId in request." }, "394105": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Sum up of 'payoutPercentage' in request must be equal to 100, current value {payoutPercentage}." }, "394106": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Instrument 'instrumentId' {instrumentId} not found." }, "394107": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Instrument 'instrumentId' {instrumentId} missing in request." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." }, "395100": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was an internal error, please try again after sometime." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.finances" ] } ] } }, "/combined_shipping_rules/create_calculated_shipping_rules": { "post": { "tags": [ "combined_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.", "operationId": "createCalculatedShippingRules", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for which the API request is being executed. This header ensures that the shipping rule applies to the correct regional eBay site (e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used to define and configure calculated combined shipping and handling rules and/or change the combined payment duration.", "content": { "application/json": { "schema": { "description": "This type is used to define and configure calculated combined shipping and handling rules and/or change the combined payment duration.", "$ref": "#/components/schemas/CreateCalculatedShippingRulesRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396003": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Combined shipping rule names must be unique. Rule names cannot match existing rules in the system or be duplicated within the request." }, "396004": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRules' data. Please verify all required fields are provided with valid values." }, "396005": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleName'." }, "396006": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmount'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396008": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmountOffShippingCost'." }, "396009": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396010": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "For create operation, 'combinedShippingRuleId' is not allowed." }, "396012": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType' in 'calculatedHandlingRule'." }, "396013": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing amount data in 'calculatedHandlingRule'." }, "396019": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396021": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'weightOffTotalWeight'." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." }, "396025": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'calculatedShippingRule'." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules/create_flat_shipping_rules": { "post": { "tags": [ "combined_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.", "operationId": "createFlatShippingRules", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field specifies the eBay marketplace identifier where the operation will be executed.

This header ensures that the promotional shipping rule is applied to the correct regional marketplace (for example, EBAY_US, EBAY_GB, EBAY_DE).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used to define and configure flat-rate combined shipping rules and/or change the combined payment duration.", "content": { "application/json": { "schema": { "description": "This type is used to define and configure flat-rate combined shipping rules and/or change the combined payment duration.", "$ref": "#/components/schemas/CreateFlatShippingRulesRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396003": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Combined shipping rule names must be unique. Rule names cannot match existing rules in the system or be duplicated within the request." }, "396004": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRules' data. Please verify all required fields are provided with valid values." }, "396005": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleName'." }, "396006": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmount'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396008": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmountOffShippingCost'." }, "396009": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396010": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "For create operation, 'combinedShippingRuleId' is not allowed." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." }, "396024": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'flatShippingRule'." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules/create_promotional_shipping_rule": { "post": { "tags": [ "combined_shipping_rules" ], "description": "This method defines promotional shipping rules such as discounts or free-shipping thresholds, configurable by marketplace for the seller.", "operationId": "createPromotionalShippingRule", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site (e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used to define and configure the promotional combined shipping rule and/or change the combined payment duration.", "content": { "application/json": { "schema": { "description": "This type is used to define and configure the promotional combined shipping rule and/or change the combined payment duration.", "$ref": "#/components/schemas/CreatePromotionalShippingRuleRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396001": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'promotionalShippingRule'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396014": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified combined shipping rule data does not match any existing rules or the operation is not supported for this rule type." }, "396017": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'shippingCost'." }, "396018": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'orderAmount'." }, "396020": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'itemCount'." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules": { "get": { "tags": [ "combined_shipping_rules" ], "description": "This method retrieves all existing combined shipping rule configurations defined by the authenticated seller, including calculated, flat, and promotional types.", "operationId": "getCombinedShippingRules", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site

(e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCombinedShippingRulesPublicApiResponse" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account.readonly" ] } ] } }, "/combined_shipping_rules/update_calculated_shipping_rules": { "post": { "tags": [ "combined_shipping_rules" ], "description": "This method updates previously defined calculated shipping rules to modify discount percentages, weight offsets, or amount parameters for the seller.", "operationId": "updateCalculatedShippingRules", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site

(e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used for creating and updating calculated combined-shipping rules.", "content": { "application/json": { "schema": { "description": "This type is used for creating and updating calculated combined-shipping rules.", "$ref": "#/components/schemas/UpdateCalculatedShippingRulesRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396004": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRules' data. Please verify all required fields are provided with valid values." }, "396005": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleName'." }, "396006": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmount'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396008": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmountOffShippingCost'." }, "396009": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396011": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleId'." }, "396012": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType' in 'calculatedHandlingRule'." }, "396013": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing amount data in 'calculatedHandlingRule'." }, "396014": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified combined shipping rule data does not match any existing rules or the operation is not supported for this rule type." }, "396016": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The provided 'combinedShippingRuleName' differs from the existing combined shipping rule name. The existing name will be preserved." }, "396019": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396021": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'weightOffTotalWeight'." }, "396022": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Duplicate 'combinedShippingRuleId' found. Each rule id must be unique within the request." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." }, "396026": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'calculatedShippingRule' or 'calculatedHandlingRule'." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules/update_combined_payments": { "post": { "tags": [ "combined_shipping_rules" ], "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.", "operationId": "updateCombinedPayments", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This path parameter is used to specify eBay's marketplace ID. Specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site

(e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used for updating combined-payment settings.

It defines how multiple unpaid orders from the same buyer are combined into a single payment, including configuration parameters such as eligible duration, order-merge criteria, and marketplace context.", "content": { "application/json": { "schema": { "description": "This type is used for updating combined-payment settings.

It defines how multiple unpaid orders from the same buyer are combined into a single payment, including configuration parameters such as eligible duration, order-merge criteria, and marketplace context.", "$ref": "#/components/schemas/UpdateCombinedPaymentsRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules/update_flat_shipping_rules": { "post": { "tags": [ "combined_shipping_rules" ], "description": "This method updates existing shipping rules.", "operationId": "updateFlatShippingRules", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site

(e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used for creating and updating flat-rate combined-shipping rules.", "content": { "application/json": { "schema": { "description": "This type is used for creating and updating flat-rate combined-shipping rules.", "$ref": "#/components/schemas/UpdateFlatShippingRulesRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396004": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRules' data. Please verify all required fields are provided with valid values." }, "396005": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleName'." }, "396006": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmount'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396008": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalAmountOffShippingCost'." }, "396009": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'eachAdditionalPercentOffShippingCost'." }, "396011": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleId'." }, "396014": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified combined shipping rule data does not match any existing rules or the operation is not supported for this rule type." }, "396016": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The provided 'combinedShippingRuleName' differs from the existing combined shipping rule name. The existing name will be preserved." }, "396022": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Duplicate 'combinedShippingRuleId' found. Each rule id must be unique within the request." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." }, "396024": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'flatShippingRule'." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/combined_shipping_rules/update_promotional_shipping_rule": { "post": { "tags": [ "combined_shipping_rules" ], "description": "This method updates an existing promotional shipping rule to adjust discount thresholds, eligibility criteria, or duration for the seller.", "operationId": "updatePromotionalShippingRule", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This field header specifies the eBay marketplace identifier for this request, ensuring the operation targets the correct regional site

(e.g., EBAY_US, EBAY_GB, EBAY_DE).

For the full list of eBay marketplace values, see the https://developer.ebay.com/api-docs/sell/account/v2/types/ba:MarketplaceIdEnum type.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This type is used for updating an existing promotional combined-shipping rules.", "content": { "application/json": { "schema": { "description": "This type is used for updating an existing promotional combined-shipping rules.", "$ref": "#/components/schemas/UpdatePromotionalShippingRuleRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396000": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'currency'." }, "396001": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Missing 'promotionalShippingRule'." }, "396002": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedShippingRuleType'." }, "396007": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'combinedDuration'." }, "396014": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified combined shipping rule data does not match any existing rules or the operation is not supported for this rule type." }, "396017": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'shippingCost'." }, "396018": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'orderAmount'." }, "396020": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid or missing 'itemCount'." }, "396023": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified marketplace ID was not found." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "395000": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } }, "/user_preferences": { "get": { "tags": [ "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.", "operationId": "getUserPreferences", "parameters": [ { "name": "fieldgroups", "in": "query", "description": "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", "required": false, "schema": { "type": "string" } }, { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "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.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserPreferencesResponse" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396502": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The specified field groups are invalid. Error Details - {errorDetails}" } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "396500": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "Internal Server Error. Please try again later or contact Developer Technical Support." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account.readonly" ] } ] }, "patch": { "tags": [ "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.", "operationId": "setUserPreferences", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This required header sets the eBay marketplace, which the seller has specified. See the MarketplaceIdEnum type for the full list of values.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "The media type of the request payload.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetUserPreferencesRequest" } } }, "required": false }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "396510": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Dispatch cutoff time format is invalid. Expected format: HH:mm:ss.SSSZ" }, "396511": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The optInStatus field is included and set to 'false', no other itemsAwaitingPaymentPreferences fields can be used." }, "396512": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The removeAllExcludedUsers field is included and set to 'true', the excludedUsers array cannot be used." }, "396513": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The delayBeforeCancellingCommitment value is invalid. See the documentation for valid values." }, "396514": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The seller's account has reached the maximum number of users ({maxNo}) that can be added to the Excluded Users list." }, "396515": { "domain": "API_ACCOUNT", "category": "REQUEST", "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": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "One or more invalid user IDs included in the excludedUsers array." }, "396517": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid value specified for combinedPaymentOption field. See documentation for valid values." }, "396518": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Customization of End of Auction email is not supported for this marketplace." }, "396519": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The provided text in the templateText field exceeds the maximum allowed number of characters (1000)." }, "396520": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The provided text in the templateText field contains vulgar language or prohibited HTML content." }, "396521": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Logo URL is required but not provided." }, "396522": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The format of the logo image in the provided logoUrl field is not supported. See documentation for supported image formats." }, "396523": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Logo URL exceeds maximum allowed length of 1024 characters." }, "396524": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The marketplace does not support the Global Shipping Program and/or the user is not enrolled in the program." }, "396525": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid value specified for upsRateOption field. See documentation for valid values." }, "396526": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid value specified for fedexRateOption field. See documentation for valid values." }, "396528": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The textCustomized field is set to ‘true’, so the templateText field must also be included." }, "396529": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The textCustomized field is set to ‘false’, so the templateText field is not applicable." }, "396530": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "Invalid value specified for logoType field. See documentation for valid values." }, "396531": { "domain": "API_ACCOUNT", "category": "REQUEST", "description": "The logoType field is not set to CUSTOMIZED, so the logoUrl field is not applicable." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "396500": { "domain": "API_ACCOUNT", "category": "APPLICATION", "description": "Internal Server Error. Please try again later or contact Developer Technical Support." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.account" ] } ] } } }, "components": { "schemas": { "Amount": { "type": "object", "properties": { "currency": { "type": "string", "description": "The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD. For implementation help, refer to eBay API documentation" }, "value": { "type": "string", "description": "The monetary amount in the specified currency." } }, "description": "A complex type that describes the value of a monetary amount as represented by a global currency." }, "CalculatedHandlingRuleType": { "type": "object", "properties": { "combinedShippingRuleType": { "type": "string", "description": "This enumeration type specifies the type of combined-shipping rule applied to handling fees

(for example, weight-based, flat-rate, or percentage-based calculation method). For implementation help, refer to eBay API documentation" }, "eachAdditionalAmount": { "description": "This container specifies the additional monetary charge applied for each extra item included in a combined shipment.", "$ref": "#/components/schemas/Amount" }, "eachAdditionalAmountOffShippingCost": { "description": "This container represents the fixed monetary discount deducted from the total shipping cost for each additional item in a combined shipment.", "$ref": "#/components/schemas/Amount" }, "eachAdditionalPercentOffShippingCost": { "type": "number", "description": "This integer specifies the percentage discount applied to the total shipping cost for each additional item in a combined shipment." }, "orderHandlingAmount": { "description": "This container represents the handling fee charged for processing a combined order, if applicable.", "$ref": "#/components/schemas/Amount" } }, "description": "This type defines the structure for calculated handling fee discounts applicable when combining multiple orders." }, "CalculatedShippingRuleType": { "type": "object", "properties": { "combinedShippingRules": { "type": "array", "description": "This array lists the discount rules applied to combined shipments, detailing calculation methods and rule identifiers.

When used by a create call, there won't be any rule ID.", "items": { "$ref": "#/components/schemas/CombinedShippingRule" } }, "combinedShippingRuleType": { "type": "string", "description": "This container defines the type of combined-shipping rule applied to calculate discounts, such as weight-based, percentage-based, or flat-rate models. For implementation help, refer to eBay API documentation" } }, "description": "This type describes calculated discount rules determining total shipping cost reductions for combined items." }, "CombinedPaymentPreferencesType": { "type": "object", "properties": { "combinedPaymentOption": { "type": "string", "description": "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. For implementation help, refer to eBay API documentation" } }, "description": "This container is used to change the combined payment option. Sellers have the option to combine multiple line items from the same buyer into a combined invoice that can be paid for with one payment. See CombinedPaymentOptionEnum for a description of each value." }, "CombinedShippingRule": { "type": "object", "properties": { "combinedShippingRuleId": { "type": "string", "description": "This field represents the unique identifier for the combined-shipping discount profile,

used to reference or update a specific rule configuration." }, "combinedShippingRuleName": { "type": "string", "description": "This field specifies the unique name identifying the combined shipping discount profile within the seller’s account. This name is configured by the seller and can have a maximum of XX characters." }, "eachAdditionalAmount": { "description": "This containter defines the additional monetary charge applied for each extra item when multiple items are shipped together.", "$ref": "#/components/schemas/Amount" }, "eachAdditionalAmountOffShippingCost": { "description": "This container defines the fixed discount amount deducted from the total shipping cost for each additional item.", "$ref": "#/components/schemas/Amount" }, "eachAdditionalPercentOffShippingCost": { "type": "number", "description": "This integer specifies the percentage discount applied to the total shipping cost for each additional item in the combined order." }, "mappedCombinedShippingRuleId": { "type": "string", "description": "This field specifies the unique ID that links this combined-shipping rule to another related rule in the seller’s account." }, "weightOffTotalWeight": { "description": "This container specifies the total weight reduction applied when combining multiple items into one shipment.", "$ref": "#/components/schemas/MeasureType" } }, "description": "This container defines a discount profile schema for combined shipping, including rule IDs, names, and applicable weight or amount reductions.

Note: This field is not applicable for the create rule use case." }, "CreateCalculatedShippingRulesRequest": { "type": "object", "properties": { "calculatedHandlingRule": { "description": "This container defines the calculated handling fee rules applied to combined orders, specifying how handling costs are determined or discounted

based on combined-shipping parameters.", "$ref": "#/components/schemas/CalculatedHandlingRuleType" }, "calculatedShippingRule": { "description": "This container defines the calculated shipping rule applied to combined orders, detailing how shipping discounts or costs are computed

based on item count, total weight, or order value.", "$ref": "#/components/schemas/CalculatedShippingRuleType" }, "combinedDuration": { "type": "string", "description": "This container specifies the time window during which multiple unpaid orders can be combined into a single payment or invoice, represented by using one of the values in CombinedPaymentPeriodEnum type. For implementation help, refer to eBay API documentation" } }, "description": "This type defines the structure of a request to create calculated shipping rules, including handling, duration, and rule type details." }, "CreateFlatShippingRulesRequest": { "type": "object", "properties": { "combinedDuration": { "type": "string", "description": "This container specifies the time window during which multiple unpaid orders can be combined into a single payment or invoice, represented by using one of the values in CombinedPaymentPeriodEnum type. For implementation help, refer to eBay API documentation" }, "flatShippingRule": { "description": "This container defines the flat-rate combined-shipping rule, which applies a fixed shipping cost for multiple items shipped together.", "$ref": "#/components/schemas/FlatShippingRuleType" } }, "description": "This type represents a request to configure flat-rate combined shipping rules with specified durations and conditions." }, "CreatePromotionalShippingRuleRequest": { "type": "object", "properties": { "combinedDuration": { "type": "string", "description": "This container specifies the time window during which multiple unpaid orders can be combined into a single payment or invoice, represented by using one of the values in CombinedPaymentPeriodEnum type. For implementation help, refer to eBay API documentation" }, "promotionalShippingRule": { "description": "This container defines the promotional combined-shipping rule that offers discounts or free shipping based on order value, item count, or other qualifying conditions.", "$ref": "#/components/schemas/PromotionalShippingRuleType" } }, "description": "This type represents the request schema for creating promotional shipping rules with combined payment durations." }, "DispatchCutoffTimePreferencesType": { "type": "object", "properties": { "cutoffTime": { "type": "string", "description": "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." } }, "description": "This container is used to change the order cut-off time for same-day shipping." }, "EndOfAuctionEmailPreferencesType": { "type": "object", "properties": { "emailCustomized": { "type": "boolean", "description": "This boolean field indicates whether or not the seller is using a customized email to send to winning bidders." }, "logoCustomized": { "type": "boolean", "description": "This boolean field indicates whether or not the seller is using a customized logo in the emails that are sent to winning bidders." }, "logoType": { "type": "string", "description": "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. For implementation help, refer to eBay API documentation" }, "logoUrl": { "type": "string", "description": "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." }, "templateText": { "type": "string", "description": "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." }, "textCustomized": { "type": "boolean", "description": "This boolean field indicates whether or not the seller is using customized text in the emails that are sent to winning bidders." } }, "description": "This container shows the seller's preferences for the end-of-auction email sent to the winning bidder." }, "Error": { "type": "object", "properties": { "category": { "type": "string", "description": "Identifies the type of erro." }, "domain": { "type": "string", "description": "Name for the primary system where the error occurred. This is relevant for application errors." }, "errorId": { "type": "integer", "description": "A unique number to identify the error.", "format": "int32" }, "inputRefIds": { "type": "array", "description": "An array of request elements most closely associated to the error.", "items": { "type": "string" } }, "longMessage": { "type": "string", "description": "A more detailed explanation of the error." }, "message": { "type": "string", "description": "Information on how to correct the problem, in the end user's terms and language where applicable." }, "outputRefIds": { "type": "array", "description": "An array of request elements most closely associated to the error.", "items": { "type": "string" } }, "parameters": { "type": "array", "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.", "items": { "$ref": "#/components/schemas/ErrorParameter" } }, "subdomain": { "type": "string", "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc." } }, "description": "This type defines the fields that can be returned in an error." }, "ErrorParameter": { "type": "object", "properties": { "name": { "type": "string", "description": "The object of the error." }, "value": { "type": "string", "description": "The value of the object." } } }, "FlatShippingRuleType": { "type": "object", "properties": { "combinedShippingRules": { "type": "array", "description": "This array specifies the type of combined-shipping rule applied, such as flat-rate or cost-based.", "items": { "$ref": "#/components/schemas/CombinedShippingRule" } }, "combinedShippingRuleType": { "type": "string", "description": "This container defines the type of discount rule applied (e.g., percentage-based, fixed-rate). For implementation help, refer to eBay API documentation" } }, "description": "This type defines the flat-rate combined-shipping rule, which applies a fixed shipping cost for multiple items shipped together." }, "GetCombinedShippingRulesPublicApiResponse": { "type": "object", "properties": { "calculatedHandlingRule": { "description": "This container will show one or more calculated shipping rules set up for that seller on that ebay marketplace.

Note: This will not be returned if a calculated handling rule is not set up for that seller on that eBay marketplace", "$ref": "#/components/schemas/CalculatedHandlingRuleType" }, "calculatedShippingRule": { "description": "This container specifies the type of combined-shipping rule applied, such as flat-rate, weight-based, or cost-based.", "$ref": "#/components/schemas/CalculatedShippingRuleType" }, "combinedDuration": { "type": "string", "description": "This field is represented by one of the values in the CombinedPaymentPeriodEnum type. For implementation help, refer to eBay API documentation" }, "flatShippingRule": { "description": "This container will show one or more flat shipping rules set up for that seller on that ebay marketplace.", "$ref": "#/components/schemas/FlatShippingRuleType" }, "promotionalShippingRule": { "description": "This container shows the promotional shipping rule that is currently set up on the seller's account for the eBay marketplace.

This container will not be returned if no promotional shipping rule is currently set up on the seller's account for the eBay marketplace.", "$ref": "#/components/schemas/PromotionalShippingRuleType" } }, "description": "The base response type of the getCombinedShippingRules method.

All of a seller's calculated, flat, and promotional shipping discount rules defined for an eBay marketplace will be returned in the response, along with the current combined duration value." }, "GetItemsAwaitingPaymentPreferencesType": { "type": "object", "properties": { "autoRelist": { "type": "boolean", "description": "This boolean indicates if the item should be automatically relisted." }, "delayBeforeCancellingCommitment": { "type": "integer", "description": "This integer indicates the delay in days before cancelling the buyer's commitment.", "format": "int32" }, "excludedUsers": { "type": "array", "description": "This string returns the list of sellers excluded from unpaid item assistance.", "items": { "type": "string" } }, "optInStatus": { "type": "boolean", "description": "This boolean indicates if the unpaid item assistance is opted in." } }, "description": "This container represents the seller's preferences for the list of items that are awaiting payment." }, "GetUserPreferencesResponse": { "type": "object", "properties": { "combinedPaymentPreferences": { "description": "This container returns the combined payment preferences when the COMBINED_PAYMENT value is included through the fieldgroups query parameter or when fieldgroups=ALL. It indicates if the seller allows multiple line items from the same buyer to be combined.", "$ref": "#/components/schemas/CombinedPaymentPreferencesType" }, "dispatchCutoffTimePreference": { "description": "This container is returned when the DISPATCH_CUTOFF_TIME value is included through the fieldgroups query parameter or when fieldgroups=ALL.", "$ref": "#/components/schemas/DispatchCutoffTimePreferencesType" }, "emailShipmentTrackingNumberPreference": { "type": "boolean", "description": "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." }, "endOfAuctionEmailPreferences": { "description": "This container allows sellers to customize the email sent to buyers immediately after an auction listing is won.", "$ref": "#/components/schemas/EndOfAuctionEmailPreferencesType" }, "globalShippingProgramListingPreference": { "type": "boolean", "description": "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 GLOBAL_SHIPPING_PROGRAM value is included through the fieldgroups query parameter or when fieldgroups=ALL.
Note: The Global Shipping Program is only available for the eBay UK marketplace, and the seller must be opted into the program." }, "itemsAwaitingPaymentPreferences": { "description": "This container shows the seller’s preferences for automatically handling unpaid line items.", "$ref": "#/components/schemas/GetItemsAwaitingPaymentPreferencesType" }, "offerGlobalShippingProgramPreference": { "type": "boolean", "description": "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." }, "outOfStockControlPreference": { "type": "boolean", "description": "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." }, "overrideGspServiceWithIntlServicePreference": { "type": "boolean", "description": "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." }, "pickupDropoffSellerPreference": { "type": "boolean", "description": "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." }, "purchaseReminderEmailPreferences": { "type": "boolean", "description": "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." }, "requiredShipPhoneNumberPreference": { "type": "boolean", "description": "This boolean field indicates whether or not the buyer is required to provide a shipping phone number during checkout." }, "sellerExcludeShipToLocationPreferences": { "description": "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 setUserPreferences method.", "$ref": "#/components/schemas/SellerExcludeShipToLocationPreferencesType" }, "sellerProfilePreferences": { "description": "This container is returned when the SELLER_PROFILE value is included through the fieldgroups query parameter or when fieldgroups=ALL.", "$ref": "#/components/schemas/SellerProfilePreferencesType" }, "shippingCarrierRatePreferences": { "description": "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 SHIPPING_CARRIER_RATE value is included through the fieldgroups query parameter or when fieldgroups=ALL.
Note: This container is only applicable to the eBay US marketplace.", "$ref": "#/components/schemas/ShippingCarrierRatePreferencesType" } }, "description": "This type defines the responses for the getUserPreferences method." }, "MeasureType": { "type": "object", "properties": { "unit": { "type": "string", "description": "This field defines the unit of measure (e.g., kilograms, pounds) associated with the value field. For implementation help, refer to eBay API documentation" }, "value": { "type": "string", "description": "This field defines the numeric value representing the measurement, weight, in the specified unit." } }, "description": "This type displays measurement type with value, unit, and measurement system." }, "PayoutInstrument": { "type": "object", "properties": { "accountLastFourDigits": { "type": "string", "description": "The last four digits of the account that the seller uses to receive payouts. This may be the last four digits of a bank account or a payment processor account such as Payoneer." }, "instrumentId": { "type": "string", "description": "The unique reference identifier for a payout instrument. The instrumentId is needed to change the split-payout percentages through an updatePayoutPercentage request." }, "instrumentStatus": { "type": "string", "description": "The status of a payout instrument. Valid payout instrument statuses include:

See InstrumentStatusEnum for more details on each instrument status value.

Note: Payment accounts can only receive payouts if the status of a payout instrument is ACTIVE. For implementation help, refer to eBay API documentation" }, "instrumentType": { "type": "string", "description": "The type of account that received payouts. The value returned in this field may be:

Note: Only Payoneer is currently supported for sellers in mainland China. Card payouts are not currently available for sellers in mainland China. " }, "nickname": { "type": "string", "description": "When instrumentType returns BANK, this value is the seller-provided nickname that the seller uses to represent the bank account that receives the payout.

When instrumentType returns CARD, this value is the debit card network for the debit card that receives the payout.

When instrumentType returns a provider of digital wallet or payment processing services, the value returned is the name of the service provider (e.g., PAYONEER)

Note: Only Payoneer is currently supported for sellers in mainland China. Card payouts are not currently available for sellers in mainland China." }, "payoutPercentage": { "type": "string", "description": "The current payout percentage allocated to an instrument. For example, 50 indicates that 50% of the payout goes to the instrument." } }, "description": "This type is used to provide details about one or two of the seller's accounts that are enabled to receive payouts." }, "PayoutSettingsResponse": { "type": "object", "properties": { "payoutInstruments": { "type": "array", "description": "This array provides details about the seller's accounts defined for the seller's account.

Payment accounts can only receive payouts if the status of the payout instrument is ACTIVE.", "items": { "$ref": "#/components/schemas/PayoutInstrument" } } }, "description": "The base response type of the getPayoutSettings method." }, "PromotionalShippingRuleType": { "type": "object", "properties": { "combinedShippingRuleType": { "type": "string", "description": "This field specifies the type of combined-shipping rule applied, such as flat-rate or cost-based,

as defined in the CombinedShippingRuleTypeEnum. For implementation help, refer to eBay API documentation" }, "itemCount": { "type": "integer", "description": "This integer indicates the quantity of items that must be purchased by the buyer in order for that buyer to qualify for the promotional discount.", "format": "int32" }, "orderAmount": { "description": "This container specifies the minimum order amount required to qualify for the associated discount or promotional rule.", "$ref": "#/components/schemas/Amount" }, "shippingCost": { "description": "This container represents the total shipping cost or discounted shipping charge for the combined order.", "$ref": "#/components/schemas/Amount" } }, "description": "This type is used to represent a promotional shipping rule set up by the seller on an eBay marketplace." }, "Rate": { "type": "object", "properties": { "additionalCost": { "description": "An additional shipping cost added to the base shipping rate (i.e., shippingCost).

This amount applies only to the following rateTableBasis options:This field is returned only when it is applicable to the specified rate ID.", "$ref": "#/components/schemas/Amount" }, "rateId": { "type": "string", "description": "The unique identifier for rate information.

Note: This is a string that is automatically assigned by the system when a rate object is created." }, "shippingCategory": { "type": "string", "description": "Indicates the level of shipping service to which the shipping rate information applies.

Available shipping categories are: For implementation help, refer to eBay API documentation" }, "shippingCost": { "description": "Specifies the base shipping rate for an item.

This amount applies only to the following rateTableBasis options:", "$ref": "#/components/schemas/Amount" }, "shippingRegionNames": { "type": "array", "description": "An array of Region names to which the shipping rate information applies.

Returned values may be:", "items": { "type": "string" } }, "shippingServiceCode": { "type": "string", "description": "An enum value that indicates the shipping service used for the specified shipping rate. These enum values align with ShippingService metadata returned by a GeteBayDetails call with DetailName set to shippingServiceDetails." } }, "description": "This container details shipping rate information identified by a unique rate ID. A successful call returns the requested shipping rate information." }, "RateTableDetails": { "type": "object", "properties": { "marketplaceId": { "type": "string", "description": "Identifies the eBay marketplace to which the shipping rate table applies. For implementation help, refer to eBay API documentation" }, "name": { "type": "string", "description": "The seller-defined name for the shipping rate table. Names must be unique for each table assigned to the same seller, shippingOptionType, and eBay marketplace.

Max length: 50" }, "rates": { "type": "array", "description": "An array of rate objects associated with the specified shipping rate table. Each rate object is identified by a unique system-generated ID and defines specific shipping rate information.", "items": { "$ref": "#/components/schemas/Rate" } }, "rateTableBasis": { "type": "string", "description": "The rate calculation type provides three methods of calculating the shipping cost based on the seller's selection/input: For implementation help, refer to eBay API documentation" }, "rateTableId": { "type": "string", "description": "A unique, system-generated ID assigned to the shipping rate table when it is initially created." }, "shippingOptionType": { "type": "string", "description": "The region serviced by the shipping rate table. Valid values are: For implementation help, refer to eBay API documentation" } }, "description": "This container includes all information pertaining to a shipping rate table. A successful call returns the requested shipping rate information." }, "RateTableUpdate": { "type": "object", "properties": { "rates": { "type": "array", "description": "An array of rate objects for which shippingCost and/or additionalCost are to be updated.", "items": { "$ref": "#/components/schemas/RateUpdate" } } }, "description": "This type is used by the request payload of the updateShippingCost method to pass updated shipping cost information for a rate table identified by rateTableId." }, "RateUpdate": { "type": "object", "properties": { "additionalCost": { "description": "An additional shipping cost added to the base shipping rate (i.e., shippingCost).

This amount applies only to the following rateTableBasis options:This field is returned only when it is applicable to the specified rate ID.", "$ref": "#/components/schemas/Amount" }, "rateId": { "type": "string", "description": "The identifier for the rate object.

Note: This is a string automatically assigned by the system when the rate object is created. It cannot be changed or updated." }, "shippingCost": { "description": "This is the base shipping rate for an item.

This amount applies only to the following rateTableBasis options:", "$ref": "#/components/schemas/Amount" } }, "description": "This container defines the updated shipping cost information for a rate object identified by rateId.

To view a list of all rate objects and corresponding rateID values, issue getRateTable for the rate table identified by rateTableId." }, "SellerExcludeShipToLocationPreferencesType": { "type": "object", "properties": { "excludeShipToLocations": { "type": "array", "description": "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'.", "items": { "type": "string" } } }, "description": "This container represents the list of locations that the seller wants to exclude from shipping." }, "SellerProfilePreferencesType": { "type": "object", "properties": { "sellerProfileOptedIn": { "type": "boolean", "description": "This boolean indicates whether the seller has opted in to seller profiles." } }, "description": "This container indicates whether or not the seller is opted into Business Policies. If a seller is opted into Business Policies, they must use Payment,Return, and Shipping business policies instead of individual payment, return, and shipping fields." }, "ShippingCarrierRatePreferencesType": { "type": "object", "properties": { "fedexRateOption": { "type": "string", "description": "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. For implementation help, refer to eBay API documentation" }, "upsRateOption": { "type": "string", "description": "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. For implementation help, refer to eBay API documentation" } }, "description": "This field is included if the seller wishes to add or modify the shipping carrier rate type that is available to the seller. This field is only returned if set.
Note: This container is only applicable to the eBay US marketplace." }, "UpdateCalculatedShippingRulesRequest": { "type": "object", "properties": { "calculatedHandlingRule": { "description": "This container specifies the calculated handling rule that determines how handling fees are automatically computed based on order weight, quantity, or value in a combined shipment.", "$ref": "#/components/schemas/CalculatedHandlingRuleType" }, "calculatedShippingRule": { "description": "This container defines the calculated shipping rule that determines shipping costs or discounts based on factors such as total weight, price, or item count in a combined order.", "$ref": "#/components/schemas/CalculatedShippingRuleType" }, "combinedDuration": { "type": "string", "description": "This container specifies the duration within which multiple unpaid orders may be combined into a single invoice, represented by one of the values in the CombinedPaymentPeriodEnum type. For implementation help, refer to eBay API documentation" } }, "description": "This type is used to update calculated shipping rules." }, "UpdateCombinedPaymentsRequest": { "type": "object", "properties": { "combinedDuration": { "type": "string", "description": "This field specifies the duration within which multiple unpaid orders may be combined into a single invoice.

One of the values in the CombinedPaymentPeriodEnum type must be used in this field. For implementation help, refer to eBay API documentation" } }, "description": "This type is used to update the combined payment duration" }, "UpdateFlatShippingRulesRequest": { "type": "object", "properties": { "combinedDuration": { "type": "string", "description": "This field specifies the duration within which multiple unpaid orders may be combined into a single invoice.

One of the values in the CombinedPaymentPeriodEnum type must be used in this field. For implementation help, refer to eBay API documentation" }, "flatShippingRule": { "description": "This container defines the flat-rate combined-shipping rule, which applies a fixed shipping cost for multiple items shipped together.", "$ref": "#/components/schemas/FlatShippingRuleType" } }, "description": "This type defines a request to update flat shipping rules." }, "UpdatePayoutPercentage": { "type": "object", "properties": { "instrumentId": { "type": "string", "description": "The unique reference identifier for a payout instrument. This value is returned in the getPayoutSettings response and is needed to change split-payout percentages through an updatePayoutPercentage request." }, "payoutPercentage": { "type": "string", "description": "The user-defined payout percentage allocated to this instrument. For example, 50 indicates that 50% of the payout goes to this instrument.

The split-payout percentage must be a positive integer value from 0-100. The values of two instruments must always add up to 100%. If the values do not equal 100, the call will fail." } }, "description": "This type allows the user to change the payout percentages for two active payment instruments." }, "UpdatePayoutPercentageRequest": { "type": "object", "properties": { "payoutInstruments": { "type": "array", "description": "This array allows the seller to set the payout split percentages for two accounts enabled to receive payouts.", "items": { "$ref": "#/components/schemas/UpdatePayoutPercentage" } } }, "description": "This type is used by the request payload of the updatePayoutPercentage method to allow a seller to configure the split-payout percentages for two payout instruments." }, "UpdatePromotionalShippingRuleRequest": { "type": "object", "properties": { "combinedDuration": { "type": "string", "description": "This container specifies the duration within which multiple unpaid orders may be combined into a single invoice.

One of the values in the CombinedPaymentPeriodEnum type must be used in this field. For implementation help, refer to eBay API documentation" }, "promotionalShippingRule": { "description": "This container specifies the promotional shipping rule that offers discounts or free-shipping options based on defined order thresholds, item counts, or marketplace conditions.", "$ref": "#/components/schemas/PromotionalShippingRuleType" } }, "description": "This type defines a request to update promotional shipping rule." } }, "securitySchemes": { "api_auth": { "type": "oauth2", "description": "The security definitions for this API. Please check individual operations for applicable scopes.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.ebay.com/oauth2/authorize", "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token", "scopes": { "https://api.ebay.com/oauth/api_scope/sell.finances": "View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application", "https://api.ebay.com/oauth/api_scope/sell.account.readonly": "View your account settings", "https://api.ebay.com/oauth/api_scope/sell.account": "View and manage your account settings" } } } } } } }