openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Sales_tax API
description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information. <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Sales_tax
paths:
/sales_tax/{countryCode}/{jurisdictionId}:
get:
tags:
- Sales_tax
description: 'This call retrieves the current sales-tax table entry for a specific tax jurisdiction. Specify the jurisdiction to retrieve using the <b>countryCode</b> and <b>jurisdictionId</b> path parameters. All four response fields will be returned if a sales-tax entry exists for the tax jurisdiction. Otherwise, the response will be returned as empty.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.<br><br>However, sellers may continue to use a sales-tax table to set rates for the following US territories:<ul><li>American Samoa (AS)</li><li>Guam (GU)</li><li>Northern Mariana Islands (MP)</li><li>Palau (PW)</li><li>US Virgin Islands (VI)</li></ul>For additional information, refer to <a href="https://www.ebay.com/help/selling/fees-credits-invoices/taxes-import-charges?id=4121 " target="_blank">Taxes and import charges</a>.</p></div>'
operationId: getSalesTax
parameters:
- name: countryCode
in: path
description: This path parameter specifies the two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " title="https://www.iso.org " target="_blank">ISO 3166</a> code for the country whose sales tax table you want to retrieve.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:<ul><li><code>US</code></li><li><code>CA</code></li></ul></span>
required: true
schema:
type: string
- name: jurisdictionId
in: path
description: This path parameter specifies the ID of the sales tax jurisdiction for the tax table entry to be retrieved.<br><br>Valid jurisdiction IDs can be retrieved using the <a href="/api-docs/sell/metadata/resources/country/methods/getSalesTaxJurisdictions" target="_blank ">getSalesTaxJurisdiction</a> method of the Metadata API.<br><br><span class="tablenote"><b>Note:</b> When <code>countryCode</code> is set to <code>US</code>, the only supported values for <code>jurisdictionId</code> are:<ul><li><code>AS</code> (American Samoa)</li><li><code>GU</code> (Guam</li><li><code>MP</code> Northern Mariana Islands</li><li><code>PW (Palau)</li><li><code>VI</code> (US Virgin Islands)</li></ul></span>
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SalesTax'
'204':
description: No content
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20407':
domain: API_ACCOUNT
category: REQUEST
description: Tax table not supported for {fieldName}.
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
put:
tags:
- Sales_tax
description: 'This method creates or updates a sales-tax table entry for a jurisdiction. Specify the tax table entry you want to configure using the two path parameters: <b>countryCode</b> and <b>jurisdictionId</b>. <br><br>A tax table entry for a jurisdiction is comprised of two fields: one for the jurisdiction''s sales-tax rate and another that''s a boolean value indicating whether or not shipping and handling are taxed in the jurisdiction.<br><br>You can set up <i>sales-tax tables</i> for countries that support different <i>tax jurisdictions</i>.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.</span><br>Retrieve valid jurisdiction IDs using <b>getSalesTaxJurisdictions</b> in the Metadata API.<br><br>For details about using this call, refer to <a href="/api-docs/sell/static/seller-accounts/tax-tables.html">Establishing sales-tax tables</a>.<br><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.<br><br>However, sellers may continue to use a sales-tax table to set rates for the following US territories:<ul><li>American Samoa (AS)</li><li>Guam (GU)</li><li>Northern Mariana Islands (MP)</li><li>Palau (PW)</li><li>US Virgin Islands (VI)</li></ul>For additional information, refer to <a href="https://www.ebay.com/help/selling/fees-credits-invoices/taxes-import-charges?id=4121 " target="_blank">Taxes and import charges</a>.</p></div>'
operationId: createOrReplaceSalesTax
parameters:
- name: countryCode
in: path
description: This path parameter specifies the two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " title="https://www.iso.org " target="_blank">ISO 3166</a> code for the country for which you want to create a sales tax table entry.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:<ul><li><code>US</code></li><li><code>CA</code></li></ul>
required: true
schema:
type: string
- name: jurisdictionId
in: path
description: This path parameter specifies the ID of the tax jurisdiction for the table entry to be created.<br><br>Valid jurisdiction IDs can be retrieved using the <a href="/api-docs/sell/metadata/resources/country/methods/getSalesTaxJurisdictions" target="_blank ">getSalesTaxJurisdiction</a> method of the Metadata API.<br><br><span class="tablenote"><b>Note:</b> When <code>countryCode</code> is set to <code>US</code>, the only supported values for <code>jurisdictionId</code> are:<ul><li><code>AS</code> (American Samoa)</li><li><code>GU</code> (Guam)</li><li><code>MP</code> (Northern Mariana Islands)</li><li><code>PW</code> (Palau)</li><li><code>VI</code> (US Virgin Islands)</li></ul></span>
required: true
schema:
type: string
- 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 <b>application/json</b>.<br><br>For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: A container that describes the how the sales tax is calculated.
content:
application/json:
schema:
description: A container that describes the how the sales tax is calculated.
$ref: '#/components/schemas/SalesTaxBase'
required: true
responses:
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'20407':
domain: API_ACCOUNT
category: REQUEST
description: Tax table not supported for {fieldName}.
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
delete:
tags:
- Sales_tax
description: This call deletes a sales-tax table entry for a jurisdiction. Specify the jurisdiction to delete using the <b>countryCode</b> and <b>jurisdictionId</b> path parameters.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.</span>
operationId: deleteSalesTax
parameters:
- name: countryCode
in: path
description: This path parameter specifies the two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " title="https://www.iso.org " target="_blank">ISO 3166</a> code for the country whose sales tax table entry you want to delete.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:<ul><li><code>US</code></li><li><code>CA</code></li></ul></span>
required: true
schema:
type: string
- name: jurisdictionId
in: path
description: This path parameter specifies the ID of the sales tax jurisdiction whose table entry you want to delete.<br><br>Valid jurisdiction IDs can be retrieved using the <a href="/api-docs/sell/metadata/resources/country/methods/getSalesTaxJurisdictions" target="_blank ">getSalesTaxJurisdiction</a> method of the Metadata API.<br><br><span class="tablenote"><b>Note:</b> When <code>countryCode</code> is set to <code>US</code>, the only supported values for <code>jurisdictionId</code> are:<ul><li><code>AS</code> (American Samoa)</li><li><code>GU</code> (Guam)</li><li><code>MP</code> (Northern Mariana Islands)</li><li><code>PW</code> (Palau)</li><li><code>VI</code> (US Virgin Islands)</li></ul></span>
required: true
schema:
type: string
responses:
'204':
description: Success
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20407':
domain: API_ACCOUNT
category: REQUEST
description: Tax table not supported for {fieldName}.
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
/sales_tax:
get:
tags:
- Sales_tax
description: 'Use this call to retrieve all sales tax table entries that the seller has defined for a specific country. All four response fields will be returned for each tax jurisdiction that matches the search criteria. <br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.<br><br>However, sellers may continue to use a sales-tax table to set rates for the following US territories:<ul><li>American Samoa (AS)</li><li>Guam (GU)</li><li>Northern Mariana Islands (MP)</li><li>Palau (PW)</li><li>US Virgin Islands (VI)</li></ul>For additional information, refer to <a href="https://www.ebay.com/help/selling/fees-credits-invoices/taxes-import-charges?id=4121 " target="_blank">Taxes and import charges</a>.</p></div>'
operationId: getSalesTaxes
parameters:
- name: country_code
in: query
description: This path parameter specifies the two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " title="https://www.iso.org " target="_blank">ISO 3166</a> code for the country whose tax table you want to retrieve.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:<ul><li><code>US</code></li><li><code>CA</code></li></ul></span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/account/types/ba:CountryCodeEnum
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SalesTaxes'
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
components:
schemas:
SalesTax:
type: object
properties:
countryCode:
type: string
description: The country code enumeration value identifies the country to which this sales tax rate applies.<br><br><span class="tablenote"><b>Note:</b> Sales-tax tables are available only for the US and Canada marketplaces. Therefore, the only supported values are:<ul><li><code>US</code></li><li><code>CA</code></li></ul></span> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:CountryCodeEnum'>eBay API documentation</a>
salesTaxJurisdictionId:
type: string
description: A unique ID that identifies the sales tax jurisdiction to which the sales tax rate applies.<br><br><span class="tablenote"><b>Note:</b> When the returned <code>countryCode</code> is <code>US</code>, the only supported return values for <code>salesTaxJurisdictionId</code> are:<ul><li><code>AS</code> (American Samoa)</li><li><code>GU</code> (Guam</li><li><code>MP</code> Northern Mariana Islands</li><li><code>PW (Palau)</li><li><code>VI</code> (US Virgin Islands)</li></ul></span>
salesTaxPercentage:
type: string
description: The sales tax rate that will be applied to sales price. The <b>shippingAndHandlingTaxed</b> value will indicate whether or not sales tax is also applied to shipping and handling charges<br><br>Although it is a string, a percentage value is returned here, such as <code>7.75</code>
shippingAndHandlingTaxed:
type: boolean
description: If returned as <code>true</code>, sales tax is also applied to shipping and handling charges, and not just the total sales price of the order.
description: This type is used to provide sales tax settings for a specific tax jurisdiction.
SalesTaxBase:
type: object
properties:
salesTaxPercentage:
type: string
description: This field is used to set the sales tax rate for the tax jurisdiction set in the call URI. When applicable to an order, this sales tax rate will be applied to sales price. The <b>shippingAndHandlingTaxed</b> value will indicate whether or not sales tax is also applied to shipping and handling charges<br><br>Although it is a string, a percentage value is set here, such as <code>7.75</code>.
shippingAndHandlingTaxed:
type: boolean
description: This field is set to <code>true</code> if the seller wishes to apply sales tax to shipping and handling charges, and not just the total sales price of the order. Otherwise, this field's value should be set to <code>false</code>.
description: 'This type is used by the base request of the <b>createOrReplaceSalesTax</b>. '
SalesTaxes:
type: object
properties:
salesTaxes:
type: array
description: An array of one or more sales-tax rate entries for a specific marketplace (or all applicable marketplaces if the <b>country_code</b> query parameter is not used.<br><br>If no sales-tax rate entries are set up, no response payload is returned, but an HTTP status code of <code>204 No Content</code> is returned.
items:
$ref: '#/components/schemas/SalesTax'
description: This type is used by the root response of the <b>getSalesTaxes</b> method.
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