SetStoreCategories

Use this call to change the category configuration of a user's eBay store. You can add, delete, move, or rename a list of store categories. To call SetStoreCategories, the user must have an eBay Stores subscription and they must have created an eBay Store on the eBay website.

Usage Details

Depending on the number of listings affected, SetStoreCategories is processed either synchronously or asynchronously. If the call affects few listings, eBay processes the call synchronously. Here, processing occurs when the request is received, and the response contains the outcome in the Status field, either Complete or Failed.

If the call affects many listings, eBay processes the call asynchronously. In this case, the response indicates that the Status of the changes is Pending, and processing occurs in the background. You must make a separate call to GetStoreCategoryUpdateStatus to retrieve the outcome of SetStoreCategories when it is processed asynchronously.

Even after processing is complete, it may still take several minutes for category changes to show up on the storefront in the site UI. Store categories show up in the UI only when they have items listed in them or in a subcategory.

For information on setting up and managing eBay store categories, see Managing Store Categories.

Working with the Response

The SetStoreCategories response includes TaskID and Status fields. When the call is processed synchronously, the TaskID value is 0 and the Status indicates the outcome of the request. When the call is processed asynchronously, the TaskID value is a positive number and the Status is Pending. You must use GetStoreCategoryUpdateStatus to get the outcome of the request when SetStoreCategories is processed asynchronously.

Testing SetStoreCategories

You can test this call in the Sandbox, as follows:

1. With a test user, create an eBay Store using the Sandbox website.
2. Use GetStoreOptions to get the current list of options for the eBay Store.
3. If desired, update the store configuration by making a call to SetStore using the configuration data that you retrieved in the previous step as the base data.
4. Use SetStoreCategories to add, delete, move, and rename store categories.
5. Lastly, verify that the store configuration by calling GetStore and examining the output. Note that it might take several minutes for your changes to show up in the site UI.

Related Information

See Manage store categories.

Input

See also Samples.

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <Action> StoreCategoryUpdateActionCodeType </Action>
  <DestinationParentCategoryID> long </DestinationParentCategoryID>
  <ItemDestinationCategoryID> long </ItemDestinationCategoryID>
  <StoreCategories> StoreCustomCategoryArrayType
    <CustomCategory> StoreCustomCategoryType
      <CategoryID> long </CategoryID>
      <ChildCategory> StoreCustomCategoryType
        <CategoryID> long </CategoryID>
        <ChildCategory> StoreCustomCategoryType
          <CategoryID> long </CategoryID>
          <ChildCategory> StoreCustomCategoryType </ChildCategory>
            <!-- >>> ChildCategory can be nested within itself an unlimited number of times >>> -->
          <!-- ... more ChildCategory nodes allowed here ... -->
          <Name> string </Name>
          <Order> int </Order>
        </ChildCategory>
        <!-- ... more ChildCategory nodes allowed here ... -->
        <Name> string </Name>
        <Order> int </Order>
      </ChildCategory>
      <!-- ... more ChildCategory nodes allowed here ... -->
      <Name> string </Name>
      <Order> int </Order>
    </CustomCategory>
    <!-- ... more CustomCategory nodes allowed here ... -->
  </StoreCategories>
  <!-- Standard Input Fields -->
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</SetStoreCategoriesRequest>

Output

See also Samples.

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <CustomCategory> StoreCustomCategoryArrayType </CustomCategory>
  <Status> TaskStatusCodeType </Status>
  <TaskID> long </TaskID>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</SetStoreCategoriesResponse>

Detail Controls

DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

• Basic Call ↓ - Adds categories to an eBay store.
• Delete a Category ↓ - Deletes an existing eBay store category.
• Move Categories ↓ - Moves eBay store categories under a new parent category.
• Move to Top ↓ - Moves a category to the top of the category structure.
• Renames a Category ↓ - Renames an eBay store category.

Adds categories to an eBay store.

Description

This sample shows how to add categories to your store. Store category IDs are assigned automatically. The added categories appear in the order specified under the category set with DestinationParentCategoryID. If there are items under the specified parent category, they are moved to the category specified with ItemDestinationCategoryID.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <Action>Add</Action>
  <ItemDestinationCategoryID>1***2</ItemDestinationCategoryID>
  <DestinationParentCategoryID>1***5</DestinationParentCategoryID>
  <StoreCategories>
    <CustomCategory>
      <Name>MP3 Players and Accessories</Name>
      <Order>1</Order>
    </CustomCategory>
    <CustomCategory>
      <Name>GPS Devices</Name>
      <Order>2</Order>
    </CustomCategory>
  </StoreCategories>
</SetStoreCategoriesRequest>

Output

XML format.
<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-07T18:21:15.735Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1131</Version>
  <Build>E1131_CORE_APISELLING_19099826_R1</Build>
  <TaskID>0</TaskID>
  <Status>Complete</Status>
</SetStoreCategoriesResponse>

Back to list of samples

Deletes an existing eBay store category.

Description

This sample shows how to delete categories from an eBay store. Any items listed under the deleted categories will be moved under the category specified with ItemDestinationCategoryID.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <Action>Delete</Action>
  <ItemDestinationCategoryID>1***2</ItemDestinationCategoryID>
  <StoreCategories>
    <CustomCategory>
      <CategoryID>19227</CategoryID>
    </CustomCategory>
    <CustomCategory>
      <CategoryID>19228</CategoryID>
    </CustomCategory>
  </StoreCategories>
</SetStoreCategoriesRequest>

Output

XML format.
<?xml version="1.0" encoding="UTF-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-07T18:21:15.735Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1131</Version>
  <Build>E1131_CORE_APISELLING_19099826_R1</Build>
  <TaskID>0</TaskID>
  <Status>Complete</Status>
</SetStoreCategoriesResponse>

Back to list of samples

Moves eBay store categories under a new parent category.

Description

This sample moves two categories underneath a new parent category in an eBay store category structure.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <Action>Rename</Action>
  <ItemDestinationCategoryID>1***7</ItemDestinationCategoryID>
  <DestinationParentCategoryID>1***2</DestinationParentCategoryID>
  <StoreCategories>
    <CustomCategory>
      <CategoryID>19227</CategoryID>
      <Name>MP3 Players and Accessories</Name>
      <Order>1</Order>
    </CustomCategory>
    <CustomCategory>
      <CategoryID>19228</CategoryID>
      <Name>GPS Devices</Name>
      <Order>2</Order>
    </CustomCategory>
  </StoreCategories>
</SetStoreCategoriesRequest>

Output

The response showing that the call is being processed asynchronously.

XML format.
<?xml version="1.0" encoding="UTF-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-07T18:21:15.735Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1131</Version>
  <Build>E1131_CORE_APISELLING_19099826_R1</Build>
  <TaskID>7*8</TaskID>
  <Status>Pending</Status>
</SetStoreCategoriesResponse>

Back to list of samples

Moves a category to the top of the category structure.

Description

Moves an eBay store categories to the top level of the eBay store category structure.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <Action>Move</Action>
  <DestinationParentCategoryID>-**9</DestinationParentCategoryID>
  <StoreCategories>
    <CustomCategory>
      <CategoryID>14122</CategoryID>
      <Name>Electronics</Name>
      <Order>4</Order>
    </CustomCategory>
  </StoreCategories>
</SetStoreCategoriesRequest>

Output

The response showing that the call is being processed synchronously.

XML format.
<?xml version="1.0" encoding="UTF-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-07T18:21:15.735Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1131</Version>
  <Build>E1131_CORE_APISELLING_19099826_R1</Build>
  <TaskID>0</TaskID>
  <Status>Complete</Status>
</SetStoreCategoriesResponse>

Back to list of samples

Renames an eBay store category.

Description

This sample renames two existing eBay store categories.

Input

XML format.

<?xml version="1.0" encoding="utf-8"?>
<SetStoreCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>A*******3</eBayAuthToken>
  </RequesterCredentials>
  <Action>Rename</Action>
  <StoreCategories>
    <CustomCategory>
      <CategoryID>19227</CategoryID>
      <Name>Portable Audio</Name>
    </CustomCategory>
    <CustomCategory>
      <CategoryID>19228</CategoryID>
      <Name>Techno Gadgets</Name>
    </CustomCategory>
  </StoreCategories>
</SetStoreCategoriesRequest>

Output

XML format.
<?xml version="1.0" encoding="UTF-8"?>
<SetStoreCategoriesResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2019-11-07T18:21:15.735Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1131</Version>
  <Build>E1131_CORE_APISELLING_19099826_R1</Build>
  <TaskID>0</TaskID>
  <Status>Complete</Status>
</SetStoreCategoriesResponse>

Back to list of samples

Change History