--- title: Stores API description: "The **Stores API** provides stores-related resources for third-party developers. These resources let you retrieve basic store information such as store name, description, store url, return store category hierarchy, add/rename/move/delete a single user's eBay store category, and retrieve the processing status of these tasks. The Stores API resource methods require an access token created with the [authorization code grant](https://developer.ebay.com/api-docs/static/oauth-authorization-code-grant.html) flow. See each method for their respective OAuth scopes." api_version: 1 api_name: stores_api api_type: REST api_group: sell/stores_api source_url: html: https://developer.ebay.com/develop/api/sell/stores_api md: https://developer.ebay.com/develop/api/sell/stores_api.md --- # Stores API API The **Stores API** provides stores-related resources for third-party developers. These resources let you retrieve basic store information such as store name, description, store url, return store category hierarchy, add/rename/move/delete a single user's eBay store category, and retrieve the processing status of these tasks. The Stores API resource methods require an access token created with the [authorization code grant](https://developer.ebay.com/api-docs/static/oauth-authorization-code-grant.html) flow. See each method for their respective OAuth scopes. ## API Information **Title:** Store API **Version:** 1 **Description:** The **Stores API** provides stores-related resources for third-party developers. These resources let you retrieve basic store information such as store name, description, store url, return store category hierarchy, add/rename/move/delete a single user's eBay store category, and retrieve the processing status of these tasks. The Stores API resource methods require an access token created with the [authorization code grant](/api-docs/static/oauth-authorization-code-grant.html) flow. See each method for their respective OAuth scopes. **Base Path:** /sell/stores/v1 ## API Methods The following API methods are available: ### getStoreCategories #### GET /store/categories **Description:** This method is used to retrieve the category hierarchy for an eBay user's store. **Note:** Three levels of store categories are supported. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### addStoreCategory #### POST /store/categories **Description:** This method is used to add a single new custom category to a user's eBay store through an asynchronous request. A successful call returns the **getStoreTask** URI in the Location response header. Call **getStoreTask** (or **getStoreTasks**) method to retrieve the status of the add category operation. **Note:** Three levels of store categories are supported. **Important!** If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### renameStoreCategory #### PUT /store/categories/{category_id} **Description:** This method is used to rename the single category of a user's eBay store through a synchronous request. **Parameters:** - **category_id** (string) *required* - The unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID. This is the category that is to be renamed. - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### deleteStoreCategory #### DELETE /store/categories/{category_id} **Description:** This method is used to delete one custom category of a user's eBay store through an asynchronous request. A successful call returns the **getStoreTask** URI in the Location response header. Call **getStoreTask** (or **getStoreTasks**) method to retrieve the status of the delete category operation. **Important!** If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request. **Parameters:** - **category_id** (string) *required* - The unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID. The [**getStoreCategories**](/api-docs/sell/stores/resources/store/methods/getStoreCategories) method can be used to retrieve store category IDs. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### getStore #### GET /store **Description:** This method is used to retrieve information for an eBay user's store such as store name, store URL, and description. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### getStoreTask #### GET /store/tasks/{task_id} **Description:** This method retrieves the current status of a recent store operation. The unique identifier of the task is passed in as a path parameter. **Parameters:** - **task_id** (string) *required* - The unique identifier of an eBay Store async task. A taskId value is returned in the response of other successful calls. (e.g., addStoreCategory, moveStoreCategory, deleteStoreCategory). **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### getStoreTasks #### GET /store/tasks **Description:** This method retrieves the status of all async store tasks for a store. Every task is set as FAILED or COMPLETED once it's execution time reaches 24 hours. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ### moveStoreCategory #### POST /store/categories/move_category **Description:** This method is used to move an existing user's eBay store custom category through an asynchronous request. A successful call returns the **getStoreTask** URI in the Location response header. The user calls **getStoreTask** to retrieve the status of the move category operation. **Important!** If you initiate a category change, you cannot make additional category changes until the previous change request has completed. Use getStoreTask (or getStoreTasks) method to get latest status of your last request. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/sell.stores` ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 225002 - API_STORES **Description:** User must have an active store subscription. #### 225001 - API_STORES **Description:** Input data for {param} is invalid or missing. Please check API documentation. #### 225003 - API_STORES **Description:** You cannot make additional category changes until your previous change request has completed. Use getStoreTask method to get latest status of your last request. #### 226000 - API_STORES **Description:** You cannot have duplicate category names under the same category parent. #### 226001 - API_STORES **Description:** Invalid characters found in {category\_name}. Please see documentation for more information on recommended valid characters. #### 226002 - API_STORES **Description:** Category name can not be empty, or 'Other'. #### 226003 - API_STORES **Description:** Category name {category\_name} exceeds the maximum allowed length of {max\_length} characters. #### 226004 - API_STORES **Description:** Custom store category count exceeds the maximum allowed count {max\_count}. #### 226005 - API_STORES **Description:** Custom store category {category\_name} exceeds the maximum allowed category depth {depth\_limit}. #### 226006 - API_STORES **Description:** Category id {category\_id} doesn't exist for the store. #### 226100 - API_STORES **Description:** The provided task\_id could not be matched to a store category request for the store. ### APPLICATION Errors #### 225000 - API_STORES **Description:** Internal server error encountered. If this problem persists, contact the eBay Developers Program for support. ## Types ### AddStoreCategoryRequestType **Description:** The base request type of the **addStoreCategory** method. It is used to provide the name and location for the new category. **Type:** object **Properties:** - **categoryName** (string) - The seller-specified name of the custom category. **Max Length:** 35 - **destinationParentCategoryId** (string) - This field is used to specify the parent category to which the new category belongs. To specify the new category as a top-level category, set the value of this field to -999, or just omit this field, as the default value is -999. The [getStoreCategories](/develop/api/sell/stores_api#sell-stores_api-store-getstorecategories) method can be used to retrieve store category IDs. **Default: ROOT** category ID**(-999)** if it's null. - **listingDestinationCategoryId** (string) - If the store category specified as the **destinationParentCategoryId** is a leaf category with active listings, those listings are moved to the store category identified through this **listingDestinationCategoryId**. If this field is omitted, the new store category being added under the parent category inherits those listings. The [getStoreCategories](/develop/api/sell/stores_api#sell-stores_api-store-getstorecategories) method can be used to retrieve store category IDs. **Default:** Newly added category ID if it's null. ### DeleteStoreCategoryRequestType **Description:** The base request type of the **deleteStoreCategory** method. It is used to provide a new category home for the listings that are currently in the store category to be deleted. **Type:** object **Properties:** - **listingDestinationCategoryId** (string) - This field is only needed if the category to be deleted or any of its children categories have one or more active listings. The operation will fail otherwise. All active listings in or under the category to be deleted will be moved to the store category specified in this field. The [getStoreCategories](/develop/api/sell/stores_api#sell-stores_api-store-getstorecategories) method can be used to retrieve store category IDs. **Default: OTHER** category ID **(1)** if it's null. ### GetStoreCategoriesResponseType **Description:** The base response type of the **getStoreCategories** method. This type provides the entire category hierarchy for the store. **Type:** object **Properties:** - **storeCategories** (array) - An array of top-level categories defined for the eBay store. A **childrenCategories** array is used for second and third-level categories, if defined for the store. ### GetStoreResponseType **Description:** The base response type of the **getStore** method. It is used to describe a seller's eBay store, and includes the eBay Store name, the description of the store, the URL to the eBay Store. **Type:** object **Properties:** - **description** (string) - The seller-provided description of the eBay Store. **Max length:** 300 - **lastOpenedTime** (string) - Indicates the time the store was last opened or reopened. - **logo** (StoreLogoType) - This container provides information about a Store logo. - **name** (string) - The name of the eBay Store. The name is shown at the top of the Store page. **Max length:** 35 - **url** (string) - The complete URL of the user's store. - **urlPath** (string) - The relative URL path of the Store. **Max length:** 58 ### GetStoreTaskResponseType **Description:** The base response type of the **getStoreTask** method. **Type:** object **Properties:** - **task** (StoreTaskType) - This container provides detailed information about the status of the store task. ### GetStoreTasksResponseType **Description:** The base response type of the **getStoreTasks** method. **Type:** object **Properties:** - **task** (array) - This array provides detailed information about the status of one or more store tasks. ### MoveStoreCategoryRequestType **Description:** The base request type of the **moveStoreCategory** method. It is used to provide the name of the category to be moved and its new location. **Type:** object **Properties:** - **categoryId** (string) - The unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID. This is the category that is moved. - **destinationParentCategoryId** (string) - The new parent category of the category to be moved is specified in this field. If the category is being moved to level 1 category, set this value to **\-999**. - **listingDestinationCategoryId** (string) - This field is only needed if the category to be moved is a leaf category with listings, but a category that becomes a non-leaf category after the move. The listings of the category to be moved are moved to the category specified in this field. ### RenameStoreCategoryRequestType **Description:** The base request type of the **renameStoreCategory** method. It is used to rename a customized eBay Store category. **Type:** object **Properties:** - **categoryName** (string) - The seller-specified name of the custom category. This is the new name of the category specified through path parameter. **Max Length:** 35 ### StoreCategoryType **Description:** This type is used to provide details about a customized eBay Store category. **Type:** object **Properties:** - **categoryId** (string) - Unique identifier of an eBay Store's custom category. eBay auto-generates this identifier when a seller establishes a custom store category. This category ID should not be confused with an eBay category ID. - **categoryName** (string) - The seller-specified name of the custom category. - **childrenCategories** (array) - This array is returned to show second and third-level store categories. eBay Stores support up to three category levels. - **level** (integer) - The level indicates the category level of the category tree. **Note:** Three levels of store categories are supported. All categories belonging to the same parent should have the same level. - **order** (integer) - The order in which the custom store category appears in the list of store categories when the eBay store is visited. ### StoreLogoType **Description:** This type is used to provide url of the seller's store logo. **Type:** object **Properties:** - **url** (string) - The URL of the seller's store logo. ### StoreTaskStatusEnum **Description:** This enumerated type is used to provide the processing status of a task. | - **COMPLETED**: The category changes completed successfully. - **FAILED**: The category changes failed. - **PENDING**: The category changes are still pending. **Type:** object ### StoreTaskType **Description:** This type is used to provide details about the status of the Store Task. **Type:** object **Properties:** - **id** (string) - The unique identifier of an eBay Store task. - **message** (string) - This field provides a textual description on the status of the task, and could help user troubleshoot any issues if there is an issue with eBay creating the task. - **status** (StoreTaskStatusEnum) - The enumeration value here indicates the processing status of the task. See the **StoreTaskStatusEnum** type for more information on supported status values. - **type** (StoreTaskTypeEnum) - The enumeration value indicates the task type. ### StoreTaskTypeEnum **Description:** This enumerated type is used to provide the kind of store task being performed. | - **ADD_STORE_CATEGORY**: Add a single category to the store. - **MOVE_STORE_CATEGORY**: Move a single category from one place in the store category structure to another. - **DELETE_STORE_CATEGORY**: Delete a single category from the store. **Type:** object ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-06-18T11:16:17.405Z*