api-specs/sell_account_v2_oas3.yaml
openapi: 3.0.0
info:
title: Rate Table API
description: This API allows sellers to retrieve and manage their custom shipping rate tables.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: 2.0.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 <b>rate_table_id</b> path parameter.<br><br><b>getRateTable</b> currently supports the retrieval of rate tables for the following eBay marketplace IDs:<ul><li><code>EBAY_AU</code></li><li><code>EBAY_CA</code></li><li><code>EBAY_DE</code></li><li><code>EBAY_ES</code></li><li><code>EBAY_FR</code></li><li><code>EBAY_GB</code></li><li><code>EBAY_IT</code></li><li><code>EBAY_US</code></li></ul><span class="tablenote"><b>Note:</b> To retrieve a list of all <b>rateTableId</b> values, issue a <a href="/api-docs/sell/account/resources/rate_table/methods/getRateTables " target="_blank">getRateTables</a> call (part of <a href="/api-docs/sell/account/static/overview.html " target="_blank">Account API V1</a>,) with no <b>countryCode</b> query parameter specifed. This will return a list of all shipping rate tables defined for each marketplace and their corresponding <b>rateTableId</b> values.</span><br/><br/> A successful call returns detailed information for the specified shipping rate table.
operationId: getRateTable
parameters:
- name: rate_table_id
in: path
description: The unique identifier for the shipping rate table. This identifier is generated by eBay when a shipping rate table is first created.<br/><br/><span class="tablenote"><strong>Note:</strong> To retrieve a list of all <b>rateTableId</b> values, issue a <a href="/api-docs/sell/account/resources/rate_table/methods/getRateTables" target="_blank">getRateTables</a> call (part of <a href="/api-docs/sell/account/static/overview.html " target="_blank">Account API V1</a>,) with no <b>countryCode</b> query parameter specifed. This will return a list of all shipping rate tables defined for each marketplace and their corresponding <b>rateTableId</b> values.</span>
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 <b>shippingCost</b> and/or <b>additionalCost</b> information for an existing shipping rate table identified by the <b>rate_table_id</b> path parameter.<br/><br/><span class="tablenote"><b>Note:</b> To retrieve a list of all <b>rateTableId</b> values, issue a <a href="/api-docs/sell/account/resources/rate_table/methods/getRateTables " target="_blank">getRateTables</a> call (part of <a href="/api-docs/sell/account/static/overview.html " target="_blank">Account API V1</a>,) with no <b>countryCode</b> query parameter specifed. This will return a list of all shipping rate tables and corresponding <b>rateTableId</b> values.</span><br/><br/>A successful call returns an HTTP status code of <b>204 No Content</b>.
operationId: updateShippingCost
parameters:
- name: rate_table_id
in: path
description: The unique identifier for the shipping rate table. This identifier is generated by eBay when a shipping rate table is first created.<br/><br/><span class="tablenote"><strong>Note:</strong> To retrieve a list of all <b>rateTableId</b> values, issue a <a href="/api-docs/sell/account/resources/rate_table/methods/getRateTables" target="_blank">getRateTables</a> call (part of <a href="/api-docs/sell/account/static/overview.html " target="_blank">Account API V1</a>,) with no <b>countryCode</b> query parameter specifed. This will return a list of all shipping rate tables defined for each marketplace and their corresponding <b>rateTableId</b> values.
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
components:
schemas:
Amount:
type: object
properties:
currency:
type: string
description: The base currency applied to the <b>value</b> field to establish a monetary amount.<br/><br/>The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is <code>CAD</code>. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
value:
type: string
description: The monetary amount in the specified <b>currency</b>.
description: A complex type that describes the value of a monetary amount as represented by a global currency.
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.
Rate:
type: object
properties:
additionalCost:
description: 'An additional shipping cost added to the base shipping rate (i.e., <b>shippingCost</b>).<br/><br/>This amount applies only to the following <b>rateTableBasis</b> options:<ul><li><b>WEIGHT</b>: This is a cost per unit weight and is calculated using the weight of the item(s) being shipped.</li><li><b>SURCHARGE</b>: This is a flat amount that is added to the base shipping rate.</li></ul>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.<br/><br/><span class="tablenote"><strong>Note:</strong> This is a string that is automatically assigned by the system when a rate object is created.</span>
shippingCategory:
type: string
description: 'Indicates the level of shipping service to which the shipping rate information applies.<br/><br/>Available shipping categories are:<ul><li><b>ONE_DAY</b>: <i>This option is not supported when <b>shippingOptionType</b> is INTERNATIONAL.</i> </li><li><b>EXPEDITED</b></li><li><b>STANDARD</b></li><li><b>ECONOMY</b></li><li><b>EXPRESS</b>: <i>This option is supported only when <b>MarketplaceId</b> is <code>EBAY_DE</code> (Germany)</i></li></ul> For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/account/types/api:ShippingCategoryEnum''>eBay API documentation</a>'
shippingCost:
description: 'Specifies the base shipping rate for an item.<br/><br/>This amount applies only to the following <b>rateTableBasis</b> options:<ul><li><b>ITEM</b>: This is a flat rate shipping cost per item being shipped.</li><li><b>WEIGHT</b>: This is a cost per unit weight and is calculated using the weight of the item(s) being shipped.</li></ul>'
$ref: '#/components/schemas/Amount'
shippingRegionNames:
type: array
description: An array of Region names to which the shipping rate information applies.<br/><br/>Returned values may be:<ul><li>Geographical Regions (e.g., <code>Worldwide</code>, <code>Europe</code>, and <code>Middle East</code>)</li><li>Individual countries identified by a two-digit code such as <code>US</code> (United States), <code>CA</code> (Canada), and <code>GB</code> (United Kingdom)</li><li>US states and/or Canadian provinces identified by a two-digit code such as <code>NY</code> (New York) or <code>SK</code> (Saskatchewan)</li><li>Domestic Regions such as <code>AK/HI</code> (Alaska/Hawaii)</li></ul>
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 <b>ShippingService</b> metadata returned by a <b>GeteBayDetails</b> call with <b>DetailName</b> set to <code>shippingServiceDetails</code>.
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 <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:MarketplaceIdEnum'>eBay API documentation</a>
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.<br/><br/><b>Max length:</b> 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:<ul><li><b>ITEM</b>: Specifies the flat rate shipping cost that buyers in the specified shipping region will pay. When this option is selected, information specified in the rate table overrides all shipping options/costs that are specified at the listing level. Buyers in the specified regions will only see the services provided in the rate table. Buyers in other regions that are not specified in the rate table will see the shipping services associated with the listing.</li><li><b>WEIGHT</b>: Seller can provide minimum shipping cost and an additional shipping cost per pound. The additional cost will be calculated based on the weight the seller provide at the time of listing. Buyers will see the total shipping cost and won’t see these calculations. Buyers in the specified regions will only see the services provided in the rate table. Buyers in other regions that were not specified in the rate table, will see the shipping services associated with the listing.</li><li><b>SURCHARGE</b>: Lists surcharges for buyers within specified regions, or indicates a flat amount added to the shipping cost specified within an item''s listing. Buyers will see only the total shipping cost as well as shipping services associated with the item''s listing. If a SURCHARGE is specified in the rate table for certain regions, buyers in those regions will see the (shipping cost + SURCHARGE) total.</li></ul> For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/account/types/api:ShippingRateCalculationEnum''>eBay API documentation</a>'
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:<ul><li><b>DOMESTIC</b>: Indicates that the shipping rate table applies to shipping destinations within the country in which an item has been listed (i.e., the <i>source</i> country).</li><li><b>INTERNATIONAL</b>: Indicates that the shipping rate table applies to shipping destinations outside of the country in which an item has been listed.</li></ul> For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/account/types/api:ShippingOptionTypeEnum''>eBay API documentation</a>'
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 <b>shippingCost</b> and/or <b>additionalCost</b> are to be updated.
items:
$ref: '#/components/schemas/RateUpdate'
description: This type is used by the request payload of the <b>updateShippingCost</b> method to pass updated shipping cost information for a rate table identified by <b>rateTableId</b>.
RateUpdate:
type: object
properties:
additionalCost:
description: 'An additional shipping cost added to the base shipping rate (i.e., <b>shippingCost</b>).<br/><br/>This amount applies only to the following <b>rateTableBasis</b> options:<ul><li><b>WEIGHT</b>: This is a cost per unit weight and is calculated using the weight of the item(s) being shipped.</li><li><b>SURCHARGE</b>: This is a flat amount that is added to the base shipping rate.</li></ul>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.<br/><br/><span class="tablenote"><strong>Note:</strong> This is a string automatically assigned by the system when the rate object is created. It cannot be changed or updated.</span>
shippingCost:
description: 'This is the base shipping rate for an item.<br/><br/>This amount applies only to the following <b>rateTableBasis</b> options:<ul><li><b>ITEM</b>: This is a flat rate shipping cost per item being shipped.</li><li><b>WEIGHT</b>: This is a cost per unit weight and is calculated using the weight of the item(s) being shipped.</li></ul>'
$ref: '#/components/schemas/Amount'
description: This container defines the updated shipping cost information for a rate object identified by <b>rateId</b>.<br/><br/>To view a list of all rate objects and corresponding <b>rateID</b> values, issue <b>getRateTable</b> for the rate table identified by <b>rateTableId</b>.
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.account.readonly: View your account settings
https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings