---
schema_version: "1"
id: 78a5ab79e4f4efb657861a27b0971608eb63b1e612edd42dccbea5a3cf0797e2
title: Salesforce Commerce Search Category Pinning Rules API
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-product-search-category-pinning-rules-ref.md
canonical_url: https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref
source_site: developer.salesforce.com
content_type: documentation
content_hash: f9541dfffb32c2955a9dfae3d13d70413f03c2a1e9cd7d920cca93ba98eb21b6
products:
  - B2B Commerce Developer Guide
  - Salesforce APIs
---
Salesforce Commerce Search Category Pinning Rules API

# Salesforce Commerce Search Category Pinning Rules API

Use category pinning rules to pin specific products to fixed positions on a category's browse-results page. When a shopper browses the category, pinned products appear at the configured positions regardless of the default sort order.

**Version:** v67.0

## Servers

*   `https://api.salesforce.com/services/data/{version}`
    *   `version (default v67.0): v67.0 Salesforce API version`

## Operations

### GET Get category pinning rules

`GET /commerce/management/webstores/{webstoreId}/search/category-pinning-rules`

Operation ID: `getSearchCategoryPinningRules`. Tags: CategoryPinningRulesCollection.

Collection of category pinning rules configured for a web store.

Returns a paginated list of category pinning rules for the specified web store. To page through results, pass `pageSize` and `pageToken`. Get `pageToken` from the `pageToken=` query parameter in the previous response's `nextPageUrl` and use that value, not the full URL. Each response includes the `count`, `currentPageUrl`, `nextPageUrl`, and `sortOrder` fields alongside the `categoryPinningRules` array. On the last page, `nextPageUrl` is `null`. A web store can have up to 100 category pinning rules, so a request with `pageSize=100` returns a web store's rules in a single page.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `pageToken` (query, string) Opaque cursor that identifies the page of results to return. To get the next page, use the `pageToken` value from the previous response's `nextPageUrl`. If you don't specify a value, the first page is returned.
*   `pageSize` (query, integer) Number of rules to return per page. Valid values are from 1 through 100. If you don't specify a value, the default size is 50.  
    Default: `50`. Minimum: 1. Maximum: 100. Example: `50`.

#### Responses

*   **200** The web store's category pinning rules. Returns an empty `categoryPinningRules` array when the web store has no rules.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRulesCollectionOutputRepresentation`.
    
    _Example: CollectionResponse_ Collection of category pinning rules
    
    ```
    {
      "categoryPinningRules": [
        {
          "id": "1pJxx0000004C92EAE",
          "name": "Holiday Drill Promotion",
          "categoryId": "0ZGxx0000004CaGGAU",
          "locales": [
            "en_US"
          ],
          "active": true,
          "startDate": "2026-12-01T00:00:00.000Z",
          "endDate": "2026-12-31T23:59:59.000Z",
          "pins": [
            {
              "pinnedProductId": "01txx0000006i2SAAQ",
              "position": 1
            },
            {
              "pinnedProductId": "01txx0000006i2TAAQ",
              "position": 2
            }
          ]
        }
      ],
      "count": 1,
      "currentPageUrl": "/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50",
      "nextPageUrl": null,
      "sortOrder": "createdDate ASC"
    }
    ```
    
    _Example: EmptyCollectionResponse_ Web store has no category pinning rules
    
    ```
    {
      "categoryPinningRules": [],
      "count": 0,
      "currentPageUrl": "/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50",
      "nextPageUrl": null,
      "sortOrder": "createdDate ASC"
    }
    ```
    
*   **400** The request failed validation of a pagination parameter. `errorCode` is `INVALID_API_INPUT` when `pageToken` can't be decoded, or `LIMIT_EXCEEDED` when `pageSize` is outside the range 1–100.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InvalidPageToken_ pageToken value isn't a valid pagination cursor
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid page token. The value 'not-base64!' isn't a valid pagination cursor; pass a token returned in a previous response's nextPageUrl, or omit the parameter to start from the first page."
      }
    ]
    ```
    
    _Example: PageSizeOutOfRange_ pageSize is outside the range 1–100
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "Specify a pageSize from 1 through 100. The value specified was 0."
      }
    ]
    ```
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The specified web store ID wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### POST Create a category pinning rule

`POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules`

Operation ID: `createSearchCategoryPinningRule`. Tags: CategoryPinningRulesCollection.

Collection of category pinning rules configured for a web store.

Creates a category pinning rule for the specified web store. A web store can have up to 100 category pinning rules. When the web store reaches this limit, the request fails with `errorCode: LIMIT_EXCEEDED`, and you must delete a rule before you can create another. Each category can have only one rule; creating a second rule for the same category fails with `errorCode: DUPLICATE_VALUE`.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.

#### Request body (required)

Media type: `application/json`. Schema: `SearchCategoryPinningRuleInputRepresentation`.

_Example: CreateCategoryPinningRule_ Create a category pinning rule

```
{
  "name": "Holiday Drill Promotion",
  "categoryId": "0ZGxx0000004CaGGAU",
  "locales": [
    "en_US"
  ],
  "active": true,
  "startDate": "2026-12-01T00:00:00.000Z",
  "endDate": "2026-12-31T23:59:59.000Z",
  "pins": [
    {
      "pinnedProductId": "01txx0000006i2SAAQ",
      "position": 1
    },
    {
      "pinnedProductId": "01txx0000006i2TAAQ",
      "position": 2
    }
  ]
}
```

#### Responses

*   **201** The category pinning rule that was created.
    
    Headers:
    
    *   `Location` (string (url), required)  
        Example: `https://api.salesforce.com/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules/1pJxx0000004C92EAE`.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example: CreatedRule_ Created category pinning rule
    
    ```
    {
      "id": "1pJxx0000004C92EAE",
      "name": "Holiday Drill Promotion",
      "categoryId": "0ZGxx0000004CaGGAU",
      "locales": [
        "en_US"
      ],
      "active": true,
      "startDate": "2026-12-01T00:00:00.000Z",
      "endDate": "2026-12-31T23:59:59.000Z",
      "pins": [
        {
          "pinnedProductId": "01txx0000006i2SAAQ",
          "position": 1
        },
        {
          "pinnedProductId": "01txx0000006i2TAAQ",
          "position": 2
        }
      ]
    }
    ```
    
*   **400**
    
    The request failed validation. `errorCode` indicates the cause:
    
    *   `REQUIRED_FIELD_MISSING`—a required field is missing or empty - `MALFORMED_ID`—a Salesforce ID isn't a valid 18-character ID - `LIMIT_EXCEEDED`—a limit was exceeded, such as the maximum number of pins or rules
    *   `DUPLICATE_VALUE`—a uniqueness constraint was violated, such as a duplicate rule name, pin position, or pinned product
    *   `INVALID_API_INPUT`—another input check failed, such as a length, range, date, or locale check
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InvalidRuleDefinition_ One or more required fields are missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the category pinning rule input are missing."
      }
    ]
    ```
    
    _Example: MissingRequiredField_ A required field is missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "The required field name is missing for the category pinning rule. Provide a value and try again."
      }
    ]
    ```
    
    _Example: EmptyPins_ The rule has no pins
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "Specify at least one pinned product for the category pinning rule."
      }
    ]
    ```
    
    _Example: NameTooLong_ Rule name exceeds maximum length (80 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category pinning rule name is too long. The maximum length is 80 characters."
      }
    ]
    ```
    
    _Example: CategoryIdTooLong_ Category ID exceeds maximum length (18 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category identifier is too long. The maximum length is 18 characters."
      }
    ]
    ```
    
    _Example: InvalidCategoryId_ Category ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce category identifier. The value '0ZGxxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: PastEndDate_ End date is in the past
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify an end date that's in the future."
      }
    ]
    ```
    
    _Example: InvalidDateRange_ Start date isn't before end date
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a start date that's earlier than the end date."
      }
    ]
    ```
    
    _Example: MaxPinsExceeded_ Exceeded maximum number of pins per rule (10)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "A category pinning rule can have at most 10 pinned items."
      }
    ]
    ```
    
    _Example: MaxRulesPerWebstore_ Web store already has the maximum number of category pinning rules (100)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "You can configure up to 100 category pinning rules per web store. Delete an existing rule before creating another."
      }
    ]
    ```
    
    _Example: InvalidPin_ A pin is missing a required field
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the pinned item are missing."
      }
    ]
    ```
    
    _Example: InvalidPinPosition_ Pin position is outside the range 1–10
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a pin position from 1 through 10. The value specified was 11."
      }
    ]
    ```
    
    _Example: DuplicatePinPosition_ Duplicate positions within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Pin position 1 is used more than once. Each position must be unique within a rule."
      }
    ]
    ```
    
    _Example: DuplicatePinProduct_ Duplicate product IDs within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Product 01txx0000006i2SAAQ is pinned more than once. Each product can be pinned only once within a rule."
      }
    ]
    ```
    
    _Example: InvalidPinProductId_ Pinned product ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce product identifier. The value '01txxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: InvalidLocale_ Locale isn't in underscore format, such as en\_US
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid locale in underscore format (for example, en_US). Hyphenated BCP47 tags aren't accepted."
      }
    ]
    ```
    
    _Example: DuplicateRuleName_ Another rule in the same web store already uses this name
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "The name specified for the category pinning rule conflicts with an existing rule in this web store. Specify a unique name."
      }
    ]
    ```
    
    _Example: DuplicateRuleForCategory_ Another rule in the same web store already targets this category
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "A category pinning rule already exists for category '0ZGxx0000004CaGGAU' in this web store. Delete or update the existing rule before creating another for the same category."
      }
    ]
    ```
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The specified web store ID wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### GET Get a category pinning rule

`GET /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `getSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Returns a category pinning rule for the specified web store.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Responses

*   **200** The requested category pinning rule.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example SingleRule: same as POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules 201 response._ A single category pinning rule
    
    _Example: SingleRule_ A single category pinning rule
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### PUT Replace a category pinning rule

`PUT /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `updateSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Replaces a category pinning rule for the specified web store. Include the complete rule in the request body (`name`, `categoryId`, `active`, `startDate`, `endDate`, and `pins`). A partial body fails validation. The same `categoryId` and `pins` rules as create apply, including the one-rule-per-category limit. Optional fields are replaced, not merged. If you omit `locales`, the rule resets to all locales instead of keeping the stored value. If the rule's `endDate` is already in the past, send back the same `endDate` value. Sending a different past `endDate` fails validation. This way, you can correct an expired promotion without extending its dates.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Request body (required)

Media type: `application/json`. Schema: `SearchCategoryPinningRuleInputRepresentation`.

_Example: UpdateCategoryPinningRule_ Update a category pinning rule (full replace)

```
{
  "name": "Holiday Drill Promotion - Extended",
  "categoryId": "0ZGxx0000004CaGGAU",
  "locales": [
    "en_US"
  ],
  "active": true,
  "startDate": "2026-12-01T00:00:00.000Z",
  "endDate": "2027-01-15T23:59:59.000Z",
  "pins": [
    {
      "pinnedProductId": "01txx0000006i2SAAQ",
      "position": 1
    },
    {
      "pinnedProductId": "01txx0000006i2TAAQ",
      "position": 2
    },
    {
      "pinnedProductId": "01txx0000006i2UAAQ",
      "position": 3
    }
  ]
}
```

#### Responses

*   **200** The category pinning rule that was updated.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example: UpdatedRule_ Updated category pinning rule
    
    ```
    {
      "id": "1pJxx0000004C92EAE",
      "name": "Holiday Drill Promotion - Extended",
      "categoryId": "0ZGxx0000004CaGGAU",
      "locales": [
        "en_US"
      ],
      "active": true,
      "startDate": "2026-12-01T00:00:00.000Z",
      "endDate": "2027-01-15T23:59:59.000Z",
      "pins": [
        {
          "pinnedProductId": "01txx0000006i2SAAQ",
          "position": 1
        },
        {
          "pinnedProductId": "01txx0000006i2TAAQ",
          "position": 2
        },
        {
          "pinnedProductId": "01txx0000006i2UAAQ",
          "position": 3
        }
      ]
    }
    ```
    
*   **400** The request failed validation. A replace runs the same checks as create and returns the same `errorCode` values (`REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, `DUPLICATE_VALUE`, or `INVALID_API_INPUT`). See the create (POST) response for what each code means.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example DuplicateRuleForCategory: same as POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules 400 response._ Another rule in the same web store already targets this category
    
    _Example: InvalidRuleDefinition_ One or more required fields are missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the category pinning rule input are missing."
      }
    ]
    ```
    
    _Example: NameTooLong_ Rule name exceeds maximum length (80 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category pinning rule name is too long. The maximum length is 80 characters."
      }
    ]
    ```
    
    _Example: CategoryIdTooLong_ Category ID exceeds maximum length (18 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category identifier is too long. The maximum length is 18 characters."
      }
    ]
    ```
    
    _Example: InvalidCategoryId_ Category ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce category identifier. The value '0ZGxxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: PastEndDate_ End date is in the past
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify an end date that's in the future."
      }
    ]
    ```
    
    _Example: InvalidDateRange_ Start date isn't before end date
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a start date that's earlier than the end date."
      }
    ]
    ```
    
    _Example: MaxPinsExceeded_ Exceeded maximum number of pins per rule (10)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "A category pinning rule can have at most 10 pinned items."
      }
    ]
    ```
    
    _Example: InvalidPin_ A pin is missing a required field
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the pinned item are missing."
      }
    ]
    ```
    
    _Example: InvalidPinPosition_ Pin position is outside the range 1–10
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a pin position from 1 through 10. The value specified was 11."
      }
    ]
    ```
    
    _Example: DuplicatePinPosition_ Duplicate positions within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Pin position 1 is used more than once. Each position must be unique within a rule."
      }
    ]
    ```
    
    _Example: DuplicatePinProduct_ Duplicate product IDs within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Product 01txx0000006i2SAAQ is pinned more than once. Each product can be pinned only once within a rule."
      }
    ]
    ```
    
    _Example: InvalidPinProductId_ Pinned product ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce product identifier. The value '01txxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: InvalidLocale_ Locale isn't in underscore format, such as en\_US
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid locale in underscore format (for example, en_US). Hyphenated BCP47 tags aren't accepted."
      }
    ]
    ```
    
    _Example: DuplicateRuleName_ Another rule in the same web store already uses this name
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "The name specified for the category pinning rule conflicts with an existing rule in this web store. Specify a unique name."
      }
    ]
    ```
    
    _Example: DuplicateRuleForCategory_ Another rule in the same web store already targets this category
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### DELETE Delete a category pinning rule

`DELETE /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `deleteSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Deletes a category pinning rule for the specified web store.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Responses

*   **204** The category pinning rule was deleted.
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

## Schemas

### SearchCategoryPinningRulesCollectionOutputRepresentation

A paginated list of category pinning rules for a web store. `categoryPinningRules` is always present, and is an empty array when the web store has no rules or the requested page is past the end of the list. The `count`, `currentPageUrl`, `nextPageUrl`, and `sortOrder` fields are always present, and `nextPageUrl` is `null` on the last page. Because a web store can have up to 100 rules, a request with `pageSize=100` returns all of them in one page.

*   `categoryPinningRules` (_array of SearchCategoryPinningRuleOutputRepresentation_, required) The category pinning rules on this page.
*   `count` (_integer_, required) Number of rules on this page.  
    Example: `1`.
*   `currentPageUrl` (_string_, required) URL of the current page, including the resolved `pageToken` and `pageSize` query parameters. Always present on a successful response.  
    Example: `/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50`.
*   `nextPageUrl` (_string_, required, nullable) The URL of the next page, or `null` when there are no more rules.
*   `sortOrder` (_string_, required) Sort order applied to the list. Currently always `createdDate ASC`. Additional sort orders might be supported in future API versions.  
    Example: `createdDate ASC`.

### ErrorRepresentationList

Error response returned on every unsuccessful request. It's a JSON array that contains a single error object—for example, `[{ "errorCode": "DUPLICATE_VALUE", "message": "..." }]`.

Array of `ErrorRepresentation`.

Minimum items: 1. Maximum items: 1.

### SearchCategoryPinningRuleInputRepresentation

The category pinning rule to create or replace.

*   `name` (_string_, required) The name of the category pinning rule. Must be unique within the web store. Maximum length is 80 characters.  
    Minimum length: 1. Maximum length: 80. Example: `Holiday Drill Promotion`.
*   `categoryId` (_string (Id)_, required) The ID of the category that the rule applies to. Must be a valid 18-character Salesforce ID for a product category. Each category can have only one rule.  
    Example: `0ZGxx0000004CaGGAU`.
*   `locales` (_array of string_) Locale codes that the rule applies to, in underscore format, such as `en_US`. Hyphenated BCP47 tags aren't accepted. An empty or omitted list applies the rule to all locales. On replace (PUT), omitting `locales` resets the rule to all locales instead of keeping the stored value.  
    Items: Maximum length: 10. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "en_US"
    ]
    ```
    
*   `active` (_boolean_, required) Indicates whether the category pinning rule is active.  
    Example: `true`.
*   `startDate` (_string (date-time)_, required) The start date and time of the rule, in ISO 8601 format. A past start date is allowed on create and update.  
    Example: `2026-12-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_, required) The end date and time of the rule, in ISO 8601 format. Must be after `startDate`. On create, the date must be in the future. On update, a past end date is rejected only if it differs from the stored value, so you can edit an expired rule without extending its dates.  
    Example: `2026-12-31T23:59:59.000Z`.
*   `pins` (_array of CategoryPinningRulePinInputRepresentation_, required) Ordered list of products to pin and their positions. Include 1 to 10 pins. Each position must be from 1 through 10 and unique within the rule, and each product can be pinned only once.  
    Minimum items: 1. Maximum items: 10.

### SearchCategoryPinningRuleOutputRepresentation

A category pinning rule.

*   `id` (_string (Id)_, required) The ID of the category pinning rule.  
    Example: `1pJxx0000004C92EAE`.
*   `name` (_string_, required) Name of the category pinning rule.  
    Example: `Holiday Drill Promotion`.
*   `categoryId` (_string (Id)_, required) The ID of the category that the rule applies to.  
    Example: `0ZGxx0000004CaGGAU`.
*   `locales` (_array of string_) Locale codes that the rule applies to, in underscore format, such as `en_US`. An empty list means the rule applies to all locales.
    
    _Example_
    
    ```
    [
      "en_US"
    ]
    ```
    
*   `active` (_boolean_, required) Indicates whether the category pinning rule is active.  
    Example: `true`.
*   `startDate` (_string (date-time)_, required) The start date and time of the category pinning rule, in ISO 8601 format.  
    Example: `2026-12-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_, required) The end date and time of the category pinning rule, in ISO 8601 format.  
    Example: `2026-12-31T23:59:59.000Z`.
*   `pins` (_array of CategoryPinningRulePinOutputRepresentation_, required) Ordered list of pinned products and their positions for this category.

### ErrorRepresentation

A single error returned in the error response array.

*   `errorCode` (_string_, required) Code that identifies the error condition. The client-error codes `INVALID_API_INPUT`, `REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, and `DUPLICATE_VALUE` map to HTTP 400, so you can handle a specific failure without parsing the message text.  
    Allowed values: `WEBSTORE_NOT_FOUND`, `NOT_FOUND`, `INSUFFICIENT_ACCESS`, `INVALID_API_INPUT`, `REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, `DUPLICATE_VALUE`, `UNKNOWN_EXCEPTION`.
*   `message` (_string_, required) Description of the error and how to resolve it.  
    Example: `Specify a valid WebStore ID.`.

### CategoryPinningRulePinInputRepresentation

A product to pin and its position.

*   `pinnedProductId` (_string (Id)_, required) The ID of the product to pin in the category's result list. Must be a valid 18-character Salesforce ID. A product can be pinned only once within a rule.  
    Example: `01txx0000006i2SAAQ`.
*   `position` (_integer_, required) Position in the category's result list where the product is pinned, from 1 through 10. Must be unique within the rule.  
    Minimum: 1. Maximum: 10. Example: `1`.

### CategoryPinningRulePinOutputRepresentation

A pinned product and its position.

*   `pinnedProductId` (_string (Id)_, required) The ID of the pinned product.  
    Example: `01txx0000006i2SAAQ`.
*   `position` (_integer_, required) Position where the product is pinned in the category's result list, from 1 through 10.  
    Minimum: 1. Maximum: 10. Example: `1`.