---
schema_version: "1"
id: 3437489d6a36a0f681d0a617a56c64b02c5f8f2e969cd89d5776463dbcd605fe
title: Campaigns
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/campaigns.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns
source_site: developer.salesforce.com
content_type: documentation
content_hash: 1831e259b1c0456a5a67b21e4e68fce987c6774af761a18c1bfaf7a034a6007e
products:
  - B2C Commerce API
  - Salesforce APIs
---
Campaigns

# Campaigns

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/campaigns/campaigns-oas-v1-public.yaml)

## API Overview

Campaigns enable experiences based on an optional schedule and qualifying criteria.

When an experience is assigned to a campaign, the schedule and qualifiers can only refine the containing campaign. A campaign is defined in the context of a site and is not shared among sites. A campaign can be enabled or disabled. A disabled campaign is inactive and not available to consumers. Enabled promotions contained within a disabled campaign are also inactive.

### Qualifiers

Qualifiers are requirements that must be met to enable a campaign's experience.

*   Schedule: A start and end time and date. This can be open ended at one or both ends.
*   Coupon: A coupon
*   Customer Group: Membership in a customer group.
*   Source Code: A code attached to the site URL that identifies where the customer was redirected from.

For more details, see [Qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_qualifiers.htm&type=5) on the B2C Commerce documentation.

### Experiences

Promotion: A monetary discount or bonus item. Promotions can have additional criteria such as quantity or number of products gating the discount.

### Authentication & Authorization

The client requesting the campaign information must have access to the Campaign resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Use Cases

#### Flash Sales

Use single date promotions when you want to run a campaign for a short period of time.

For example, a '20% Off Black Friday' campaign enables a 20% off promotion for registered customers on Black Friday.

#### No Date or Time Restrictions

You can also configure promotions with no time or date restrictions. This is useful when running coupon-coded promotions, or qualifier-based promotions that require certain criteria to be met.

For example, a 'Free Shipping' campaign enables a free shipping promotion when the coupon code "freeship" is added to the cart.

#### Redirections

Use redirection promotions to trigger a promotion when a customer arrives at the storefront from a specific location. You may want to use this when partnering with other resources or running external advertisements.

For example, all users directed from Facebook receive a free hat with purchase.

For more information, see [Use Source Codes as Qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_source_codesas_qualifiers.htm&type=5) in the B2C Commerce documentation.

### Related APIs

*   [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Manage promotions assigned to campaigns.
*   [Assignments](https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments?meta=Summary) — Assign promotions and discounts to campaigns.
*   [Coupons](https://developer.salesforce.com/docs/commerce/commerce-api/references/coupons?meta=Summary) — Manage coupons used as campaign qualifiers.

**Version:** 1.1.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/campaigns/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.promotions: promotions READONLY
    *   Scope sfcc.promotions.rw: promotions read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for campaigns using a search request object that allows filtering on various attributes.

`POST /organizations/{organizationId}/campaigns`

Operation ID: `campaignsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

### Supported Query Attributes

The query attribute specifies a complex query that you can use to narrow down the search. A subset of these attributes can optionally be used to sort the returned results.

| Attribute | Type | Sortable |
| --- | --- | --- |
| campaignId | String | yes |
| description | String | yes |
| enabled | Boolean | yes |
| couponId | String | no |
| customerGroup | String | no |
| sourceCode | String | no |
| startDate | Date | no |
| endDate | Date | no |
| lastModified | Date | no |

These fields can only be used in queries as conjunctions (using `AND`). If the field is used in a disjunction (`OR`), an exception is thrown.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

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

#### Responses

*   **200** Campaign search successfully executed.
    
    Media type: `application/json`. Schema: `CampaignSearchResult`.
    
    _Example: CampaignSearchResult_
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "campaignId": "mens-clothing-dress-shirts",
          "creationDate": "2019-11-06T21:12:35.000Z",
          "customerGroups": [
            "Everyone"
          ],
          "description": "This a campaign for the Mens Dress Shirts Category offering a specific banner as well as a 20% off dress shirts promotion, and a custom sort rule of product name ascending",
          "enabled": false,
          "lastModified": "2019-11-06T21:12:35.000Z"
        },
        {
          "campaignId": "mens-clothing-suits",
          "creationDate": "2019-11-06T21:12:35.000Z",
          "customerGroups": [
            "Everyone"
          ],
          "description": "This is a campaign that displays a landing banner, with a 25% discount on all suits and default sorting rule of top selling suits.",
          "enabled": false,
          "lastModified": "2019-11-06T21:12:35.000Z"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "description"
          ],
          "searchPhrase": "campaign"
        }
      },
      "offset": 1,
      "total": 4
    }
    ```
    
*   **400** Returned when the query is ill-formed.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidOperation_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-operation",
      "detail": "Failed to execute search query: wrong syntax.",
      "title": "Incorrect Syntax"
    }
    ```
    

### GET Get campaign information.

`GET /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `getCampaign`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Campaign information successfully retrieved.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example: GetCampaign_
    
    ```
    {
      "campaignId": "NewYearCampaign",
      "coupons": [
        "20%offOrdersAbove100",
        "10%offties"
      ],
      "creationDate": "2019-10-03T19:36:56.000Z",
      "customerGroups": [
        "Registered"
      ],
      "description": "Campaign for the New Year",
      "enabled": true,
      "endDate": "2020-07-31T23:09:08.000Z",
      "lastModified": "2019-10-10T14:27:00.867Z",
      "sourceCodeGroups": [
        "affiliate-email",
        "gaming-email"
      ],
      "startDate": "2019-04-01T11:30:15.000Z"
    }
    ```
    
*   **404** Returned when there is no campaign found with the given ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getCampaign404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-not-found",
      "detail": "No campaign with ID 'SpecialCampaign' in site 'SiteGenesis' could be found.",
      "title": "Not Found Error"
    }
    ```
    

### PUT Create a campaign using the information provided.

`PUT /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `createCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

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

_Example: PutCampaign_

```
{
  "campaignId": "NewWinterCampaign",
  "coupons": [
    "WinterSpecial"
  ],
  "creationDate": "2019-10-03T19:36:56.000Z",
  "customerGroups": [
    "Registered"
  ],
  "description": "Campaign for winter specials",
  "enabled": true,
  "endDate": "2020-07-31T23:09:08.000Z",
  "lastModified": "2019-10-10T14:52:47.356Z",
  "startDate": "2019-04-01T11:30:15.000Z"
}
```

#### Responses

*   **200** Campaign successfully created.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example GetCampaign: same as PUT /organizations/{organizationId}/campaigns/{campaignId} request._
    
*   **400** Returned when the ID in the request does not match the ID in the document.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('CampaignXYZ') doesn't match the ID in the URL ('NewWinterCampaign')",
      "title": "Duplicate Error"
    }
    ```
    

### DELETE Deletes a campaign with a specified ID.

`DELETE /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `deleteCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Campaign deleted successfully.

### PATCH Update a campaign with the specified information.

`PATCH /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `updateCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

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

_Example: PatchCampaign_

```
{
  "description": "Thanksgiving campaign enabling special promotions",
  "enabled": true,
  "coupons": [
    "thanksgiving",
    "special"
  ]
}
```

#### Responses

*   **200** Campaign successfully updated.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example PutCampaign: same as PUT /organizations/{organizationId}/campaigns/{campaignId} request._
    
*   **400** Returned when a campaign with the specified campaign ID already exists in the site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: updateCampaign400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-duplicate",
      "detail": "The campaign couldn't be created because of duplicate ID 'CampaignXYZ'.",
      "title": "Duplicate Error"
    }
    ```
    
*   **404** Returned when there is no campaign found with the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example getCampaign404: same as GET /organizations/{organizationId}/campaigns/{campaignId} 404 response._
    

### GET List promotions assigned to a campaign.

`GET /organizations/{organizationId}/campaigns/{campaignId}/promotions`

Operation ID: `getCampaignPromotionAssignments`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Promotion campaign assignments successfully retrieved, ordered by rank ascending.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignmentResult`.
    
    _Example: GetCampaignPromotionAssignments_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "campaign": {
            "campaignId": "NewYearCampaign",
            "description": "Campaign for the New Year",
            "enabled": true
          },
          "campaignId": "NewYearCampaign",
          "coupons": [
            "10offsku"
          ],
          "couponsBased": true,
          "customerGroups": [
            "Registered"
          ],
          "customerGroupsBased": true,
          "enabled": true,
          "promotionId": "10offsku",
          "rank": 1,
          "requiredQualifier": "all",
          "schedule": {
            "startDate": "2026-01-01T00:00:00.000Z",
            "endDate": "2026-01-31T23:59:59.000Z",
            "recurrence": {
              "dayOfWeek": [
                "monday",
                "tuesday"
              ],
              "timeOfDay": {
                "timeFrom": "09:00:00",
                "timeTo": "17:00:00"
              }
            }
          },
          "sourceCodeBased": true,
          "sourceCodeGroups": [
            "affiliate-email"
          ]
        },
        {
          "campaign": {
            "campaignId": "NewYearCampaign",
            "description": "Campaign for the New Year",
            "enabled": true
          },
          "campaignId": "NewYearCampaign",
          "coupons": [],
          "couponsBased": false,
          "customerGroups": [],
          "customerGroupsBased": false,
          "enabled": true,
          "promotionId": "freeshipping50",
          "rank": 2,
          "requiredQualifier": "any",
          "schedule": {
            "startDate": "2026-01-01T00:00:00.000Z",
            "endDate": "2026-01-31T23:59:59.000Z",
            "recurrence": {
              "dayOfWeek": [
                "saturday",
                "sunday"
              ],
              "timeOfDay": {
                "timeFrom": "00:00:00",
                "timeTo": "23:59:59"
              }
            }
          },
          "sourceCodeBased": false,
          "sourceCodeGroups": []
        }
      ],
      "total": 2
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse`.
    
    _Example: CampaignNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-not-found",
      "detail": "No campaign with ID 'NewYearCampaign' was found for site 'RefArch'.",
      "title": "Campaign Not Found"
    }
    ```
    

### GET Get a promotion campaign assignment.

`GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `getCampaignPromotionAssignment`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Promotion campaign assignment successfully retrieved.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example: GetCampaignPromotionAssignment_
    
    ```
    {
      "campaign": {
        "campaignId": "NewYearCampaign",
        "description": "Campaign for the New Year",
        "enabled": true,
        "startDate": "2026-01-01T00:00:00.000Z",
        "endDate": "2026-01-31T23:59:59.000Z"
      },
      "campaignId": "NewYearCampaign",
      "coupons": [
        "10offsku"
      ],
      "couponsBased": true,
      "customerGroups": [
        "Registered"
      ],
      "customerGroupsBased": true,
      "enabled": true,
      "promotionId": "10offsku",
      "rank": 1,
      "requiredQualifier": "any",
      "schedule": {
        "startDate": "2026-01-01T00:00:00.000Z",
        "endDate": "2026-01-31T23:59:59.000Z",
        "recurrence": {
          "dayOfWeek": [
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday"
          ],
          "timeOfDay": {
            "timeFrom": "09:00:00",
            "timeTo": "17:00:00"
          }
        }
      },
      "sourceCodeBased": true,
      "sourceCodeGroups": [
        "affiliate-email"
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example: PromotionCampaignAssignmentNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/promotion-campaign-assignment-not-found",
      "detail": "No assignment of promotion '10offsku' to campaign 'NewYearCampaign' was found for site 'RefArch'.",
      "title": "Promotion Campaign Assignment Not Found"
    }
    ```
    

### PUT Create or replace a promotion campaign assignment.

`PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `assignPromotionToCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

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

_Example: AssignPromotionToCampaign_

```
{
  "campaignId": "NewYearCampaign",
  "promotionId": "10offsku",
  "rank": 10,
  "coupons": [
    "10offsku"
  ],
  "couponsBased": true,
  "customerGroups": [
    "Registered"
  ],
  "customerGroupsBased": true,
  "sourceCodeGroups": [
    "affiliate-email"
  ],
  "sourceCodeBased": true,
  "requiredQualifier": "all",
  "schedule": {
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2026-01-31T23:59:59.000Z",
    "recurrence": {
      "dayOfWeek": [
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday"
      ],
      "timeOfDay": {
        "timeFrom": "09:00:00",
        "timeTo": "17:00:00"
      }
    }
  }
}
```

#### Responses

*   **200** Promotion campaign assignment successfully replaced.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example AssignPromotionToCampaign: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **201** Promotion campaign assignment successfully created.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example AssignPromotionToCampaign: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **400** Bad Request. The request body is ill-formed, the composite key does not match the path, or a business rule rejected the request.
    
    Media type: `application/problem+json`. Schema: `AssignmentIdMismatchErrorResponse | AssignmentBusinessRuleViolationErrorResponse`.
    
    One of: `AssignmentIdMismatchErrorResponse`, `AssignmentBusinessRuleViolationErrorResponse`.
    
    _Example: AssignmentIdMismatchErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-id-mismatch",
      "detail": "The campaignId or promotionId in the request body does not match the IDs in the request path.",
      "title": "Assignment Id Mismatch"
    }
    ```
    
    _Example: AssignmentBusinessRuleViolationErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-business-rule-violation",
      "detail": "The promotion campaign assignment could not be saved because a business rule was violated.",
      "title": "Assignment Business Rule Violation"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example: PromotionNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/promotion-not-found",
      "detail": "No promotion with ID '10offsku' was found for site 'RefArch'.",
      "title": "Promotion Not Found"
    }
    ```
    

### DELETE Unassign a promotion from a campaign.

`DELETE /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `unassignPromotionFromCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Promotion campaign assignment successfully deleted.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example PromotionCampaignAssignmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 404 response._
    

### PATCH Update a promotion campaign assignment.

`PATCH /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `updateCampaignPromotionAssignment`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

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

_Example: UpdateCampaignPromotionAssignment_

```
{
  "rank": 20,
  "coupons": [
    "10offsku",
    "15offsku"
  ]
}
```

#### Responses

*   **200** Promotion campaign assignment successfully updated.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example UpdateCampaignPromotionAssignment: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **400** Bad Request. The request body is ill-formed, the composite key does not match the path, or a business rule rejected the request.
    
    Media type: `application/problem+json`. Schema: `AssignmentIdMismatchErrorResponse | AssignmentBusinessRuleViolationErrorResponse`.
    
    One of: `AssignmentIdMismatchErrorResponse`, `AssignmentBusinessRuleViolationErrorResponse`.
    
    _Example AssignmentIdMismatchErrorResponseExample: same as PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 400 response._
    
    _Example AssignmentBusinessRuleViolationErrorResponseExample: same as PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example PromotionCampaignAssignmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### CampaignSearchResult

Document representing a campaign search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Campaign_, required) The sorted array of campaign search hits. Can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CampaignId

The ID of the campaign.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.

### Campaign

Document representing a campaign.

*   `campaignId` (_CampaignId_)
*   `coupons` (_array of CouponId_) The array of assigned coupon IDs, not sorted.
    
    _Example_
    
    ```
    [
      "20%offOrder",
      "10%offWelcomeNewUser"
    ]
    ```
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `customerGroups` (_array of CustomerGroupId_) The array of assigned customer groups, not sorted.
    
    _Example_
    
    ```
    [
      "BigShoppers",
      "NorthAmericanShoppers"
    ]
    ```
    
*   `description` (_string_) The description of the campaign.  
    Maximum length: 4000. Example: `Campaign for the New Year`.
*   `enabled` (_boolean_) The enabled flag for campaign.  
    Example: `true`.
*   `endDate` (_string (date-time)_) The date the scenario ends.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The array of assigned source code groups, not sorted.
    
    _Example_
    
    ```
    [
      "affiliate-email",
      "gaming-email"
    ]
    ```
    
*   `startDate` (_string (date-time)_) The date the scenario begins.  
    Example: `2019-10-03T19:36:56.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionCampaignAssignmentResult

Result document representing a list of promotion campaign assignments assigned to a campaign.

Includes all fields of `ResultBase`.

*   `data` (_array of PromotionCampaignAssignment_, required) The array of promotion campaign assignments, ordered by rank ascending. Can be empty.

### CampaignNotFoundErrorResponse

Returned when no campaign with the given ID exists for the requested site.

Includes all fields of `ErrorResponse`.

*   `campaignId` (_CampaignId_)
*   `siteId` (_SiteId_)

### PromotionCampaignAssignment

Document representing a promotion campaign assignment.

*   `campaign` (_object_, required) The campaign.
    
    Includes all fields of `Campaign`.
    
*   `campaignId` (_string_, required) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_, required) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_, required)
*   `customerGroups` (_array of CustomerGroupId_, required) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_, required)
*   `enabled` (_boolean_, required, read-only) Read-only. True if the assigned promotion is enabled. Derived from the promotion's enabled state; cannot be set on the assignment. Use the Promotions API to change it.  
    Example: `true`.
*   `promotionId` (_string_, required) The ID of the promotion. Use the Promotions API to fetch the full promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_, required) The rank of promotion campaign assignment.  
    Example: `1`.
*   `requiredQualifier` (_RequiredQualifier_, required)
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_, required)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_, required) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionCampaignAssignmentNotFoundErrorResponse

Returned when the promotion is not assigned to the campaign for the requested site.

Includes all fields of `ErrorResponse`.

*   `campaignId` (_CampaignId_)
*   `promotionId` (_string_) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `siteId` (_SiteId_)

### PromotionCampaignAssignmentRequest

Request body for creating or replacing a promotion campaign assignment (PUT). Omits the read-only nested campaign and promotion courtesy copies, which are response-only.

*   `campaignId` (_string_) The ID of the campaign. If supplied, must equal the campaignId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_)
*   `customerGroups` (_array of CustomerGroupId_) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_)
*   `promotionId` (_string_) The ID of the promotion. If supplied, must equal the promotionId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_) The rank of the promotion campaign assignment. Must be null or a multiple of 10 from 0 to 100 (0, 10, 20, ..., 100).  
    Minimum: 0. Maximum: 100. Multiple of: 10. Example: `10`.
*   `requiredQualifier` (_RequiredQualifier_)
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### AssignmentIdMismatchErrorResponse

Returned when the composite key in the request body does not match the campaignId or promotionId path parameters.

Includes all fields of `ErrorResponse`.

### AssignmentBusinessRuleViolationErrorResponse

Returned when a backend business rule rejects the assignment (for example, an invalid schedule or qualifier combination).

Includes all fields of `ErrorResponse`.

### PromotionNotFoundErrorResponse

Returned when the promotion referenced by the request does not exist for the requested site.

Includes all fields of `ErrorResponse`.

*   `promotionId` (_string_) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `siteId` (_SiteId_)

### PromotionCampaignAssignmentUpdate

Request body for partially updating a promotion campaign assignment (PATCH). Same properties as the create request, but all properties are optional. Omits the read-only nested campaign and promotion courtesy copies.

*   `campaignId` (_string_) The ID of the campaign. If supplied, must equal the campaignId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_)
*   `customerGroups` (_array of CustomerGroupId_) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_)
*   `promotionId` (_string_) The ID of the promotion. If supplied, must equal the promotionId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_) The rank of the promotion campaign assignment. Must be null or a multiple of 10 from 0 to 100 (0, 10, 20, ..., 100).  
    Minimum: 0. Maximum: 100. Multiple of: 10. Example: `10`.
*   `requiredQualifier` (_RequiredQualifier_)
*   `schedule` (_object_, nullable) The schedule of the assignment resource. Send schedule null to clear the assignment-level schedule.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### CouponId

The ID of the coupon.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `20%offOrder`.

### CustomerGroupId

The ID of the customer group.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `Registered`.

### SourceCodeGroupId

The ID of source code group.

Type: `string`.

Minimum length: 1. Maximum length: 28. Example: `TV-Email`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CouponsBased

Whether the coupons qualifier participates in the assignment's qualification rule. When true, the assigned coupons gate the promotion (combined with campaign-level coupons). When omitted, defaults to true if a non-empty coupons array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### CustomerGroupsBased

Whether the customer-groups qualifier participates in the assignment's qualification rule. When true, the assigned customer groups gate the promotion (combined with campaign-level customer groups). When omitted, defaults to true if a non-empty customerGroups array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### RequiredQualifier

Controls how the active qualifier types (coupons, customer groups, source-code groups) combine. 'all' requires every active qualifier type to be satisfied (AND); 'any' requires at least one (OR). Defaults to 'any' when omitted.

Type: `string`.

Allowed values: `all`, `any`. Default: `any`. Example: `any`.

### Schedule

Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded).

*   `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-31T23:59:59.000Z`.
*   `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.
    
    Includes all fields of `Recurrence`.
    

### SourceCodeBased

Whether the source-code-groups qualifier participates in the assignment's qualification rule. When true, the assigned source-code groups gate the promotion (combined with campaign-level source-code groups). When omitted, defaults to true if a non-empty sourceCodeGroups array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Recurrence

Document representing a schedule recurrence.

*   `dayOfWeek` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`.
*   `timeOfDay` (_object_) The time of the day for recurrence.
    
    Includes all fields of `TimeOfDay`.
    

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### TimeOfDay

Document representing a time schedule within a single day.

*   `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`.
*   `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```