---
title: Stores API
description: "Thie **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.0
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

Thie **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 Methods

The following API methods are available:

### 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**.

### 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.

### 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.

### 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.

### 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).

### 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.

### 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**.

### 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**.

## Error Codes

The following error codes may be returned by this API:

### REQUEST Errors

#### 225001 - API_STORES
**Description:** Input data for {param} is invalid or missing. Please check API documentation.

#### 225002 - API_STORES
**Description:** The user must have an active store subscription.

#### 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.

## Rate Limits

See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program.

## Resources

### Documentation

- [eBay Developer Program](https://developer.ebay.com/)
- [API Documentation](https://developer.ebay.com/develop/api/)
- [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets)
- [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup)

### Tools

- [API Explorer](https://developer.ebay.com/my/api_test_tool)
- [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer)

### Support

- [Developer Support](https://developer.ebay.com/support/)
- [API Status](https://developer.ebay.com/support/api-status)
- [Release Notes](https://developer.ebay.com/develop/api/release_notes/)

---
*Generated on 2026-07-07T22:26:16.346Z*