# Sanity Connect for SFCC configuration reference

This page documents all configuration options for Sanity Connect for Salesforce Commerce Cloud. For installation and setup instructions, see the [main guide](https://www.sanity.io/docs/apis-and-sdks/sanity-connect-for-salesforce-commerce-cloud).

## Site preferences

After importing the cartridge metadata, a **Sanity** custom preference group is available under **Merchant Tools → Site Preferences → Custom Preferences**. Each preference has a built-in description in Business Manager.

##### Preferences

| Preference ID | Type | Notes |
| --- | --- | --- |
| isSanityIntegrationEnabled | Boolean | Master on/off switch for the integration |
| sanityApiHostUrl | String | Default: api.sanity.io |
| sanityBearerToken | Password | API token with write access; masked in Business Manager |
| sanityProjectId | String | Found in sanity.io/manage |
| sanityDataset | String | e.g., staging, development, production |
| sanityVersion | String | e.g., v2025-11-28 |
| sanityApiQueryParams | String | e.g., returnIds=true&autoGenerateArrayKeys=true&visibility=deferred&tag=sanity.sfcc |
| isExternalImage | Boolean | Enable if your catalog uses externally hosted product images |
| sfccToSanityCategoryAttributeMappings | JSON | See Category attribute mappings below |
| sfccToSanityProductAttributeMappings | JSON | See Product attribute mappings below |

## Attribute mappings

The two mapping preferences (`sfccToSanityCategoryAttributeMappings` and `sfccToSanityProductAttributeMappings`) are JSON configuration objects that define which SFCC attributes are pushed to Sanity and what they are named in Sanity documents.

They are designed to be extended without code changes – to add a custom attribute, add a new key to the JSON and redeploy.

Each attribute entry follows this shape:

```json
"<sfccAttributeName>": {
  "sanityName": "<sanityFieldName>",
  "localized": true | false,
  "dataType": "String" | "Boolean" | "Date" | "Image" | "HTML" | "Array" | "enum"
}
```

### Category attribute mappings

Default value for `sfccToSanityCategoryAttributeMappings`:

**sfccToSanityCategoryAttributeMappings**

```json
{
  "ID": {
    "sanityName": "categoryId",
    "localized": false,
    "dataType": "String"
  },
  "creationDate": {
    "sanityName": "creationDate",
    "localized": false,
    "dataType": "Date"
  },
  "description": {
    "sanityName": "description",
    "localized": true,
    "dataType": "String"
  },
  "displayName": {
    "sanityName": "displayName",
    "localized": true,
    "dataType": "String"
  },
  "online": {
    "sanityName": "online",
    "localized": false,
    "dataType": "Boolean"
  },
  "onlineFrom": {
    "sanityName": "onlineFrom",
    "localized": false,
    "dataType": "Date"
  },
  "onlineTo": {
    "sanityName": "onlineTo",
    "localized": false,
    "dataType": "Date"
  },
  "thumbnail": {
    "sanityName": "thumbnailImage",
    "localized": false,
    "dataType": "Image"
  }
}
```

### Product attribute mappings

Default value for `sfccToSanityProductAttributeMappings`:

**sfccToSanityProductAttributeMappings**

```json
{
  "ID": {
    "sanityName": "productId",
    "localized": false,
    "dataType": "String"
  },
  "brand": {
    "sanityName": "brand",
    "localized": false,
    "dataType": "String"
  },
  "color": {
    "sanityName": "color",
    "localized": false,
    "dataType": "String"
  },
  "creationDate": {
    "sanityName": "creationDate",
    "localized": false,
    "dataType": "Date"
  },
  "isNew": {
    "sanityName": "isNew",
    "localized": false,
    "dataType": "Boolean"
  },
  "isSale": {
    "sanityName": "isSale",
    "localized": false,
    "dataType": "Boolean"
  },
  "lastModified": {
    "sanityName": "lastModified",
    "localized": false,
    "dataType": "Date"
  },
  "longDescription": {
    "sanityName": "longDescription",
    "localized": true,
    "dataType": "HTML"
  },
  "manufacturerName": {
    "sanityName": "manufacturerName",
    "localized": false,
    "dataType": "String"
  },
  "manufacturerSKU": {
    "sanityName": "manufacturerSKU",
    "localized": false,
    "dataType": "String"
  },
  "name": {
    "sanityName": "name",
    "localized": true,
    "dataType": "String"
  },
  "onlineFlag": {
    "sanityName": "onlineFlag",
    "localized": false,
    "dataType": "Boolean"
  },
  "onlineFrom": {
    "sanityName": "onlineFrom",
    "localized": false,
    "dataType": "Date"
  },
  "onlineTo": {
    "sanityName": "onlineTo",
    "localized": false,
    "dataType": "String"
  },
  "pageDescription": {
    "sanityName": "pageDescription",
    "localized": true,
    "dataType": "String"
  },
  "pageKeywords": {
    "sanityName": "pageKeywords",
    "localized": true,
    "dataType": "String"
  },
  "pageTitle": {
    "sanityName": "pageTitle",
    "localized": true,
    "dataType": "String"
  },
  "pageURL": {
    "sanityName": "pageURL",
    "localized": true,
    "dataType": "String"
  },
  "refinementColor": {
    "sanityName": "refinementColor",
    "localized": false,
    "dataType": "enum"
  },
  "searchable": {
    "sanityName": "searchable",
    "localized": false,
    "dataType": "Boolean"
  },
  "searchableIfUnavailable": {
    "sanityName": "searchableIfUnavailable",
    "localized": false,
    "dataType": "Boolean"
  },
  "shortDescription": {
    "sanityName": "shortDescription",
    "localized": true,
    "dataType": "HTML"
  },
  "size": {
    "sanityName": "size",
    "localized": false,
    "dataType": "String"
  },
  "productType": {
    "sanityName": "productType",
    "localized": false,
    "dataType": "String"
  },
  "variationAttributes": {
    "sanityName": "variationAttributes",
    "localized": false,
    "dataType": "Array"
  },
  "image": {
    "sanityName": "productImage",
    "localized": false,
    "dataType": "String"
  }
}
```

## Job step parameters

Both sync jobs (`FULL_Sanity_Export_Categories_and_Products` and `DELTA_Sanity_Export_Categories_and_Products`) use the same step-level parameters. Each locale your storefront supports requires its own job step.

### Category sync step

##### Category sync step

| Parameter | Description | Values |
| --- | --- | --- |
| isEnabled | Enable or disable this step for the given locale | true / false |
| locale | Locale to sync | Valid BM locale string, e.g. en_US, fr, de |
| sendLocalizedAttributesOnly | Send only localized attributes when enabled | true / false |

### Product sync step

##### Product sync step

| Parameter | Description | Values |
| --- | --- | --- |
| isEnabled | Enable or disable this step for the given locale | true / false |
| locale | Locale to sync | Valid BM locale string, e.g. en_US, fr, de |
| sendLocalizedAttributesOnly | Send only localized attributes when enabled | true / false |
| ingestionStrategy | Full catalog sync or delta-only | FULL / DELTA |
| includeMasterProductsOutOfStock | Include out-of-stock master products | true / false |

## Further reading

- [Sanity Connect for SFCC: installation guide](https://www.sanity.io/sanity-for-salesforce-commerce-cloud)
- [@sanity/sfcc on npm](https://www.npmjs.com/package/@sanity/sfcc): full plugin API and exports reference
- [Connector repository](https://github.com/sanity-io/sanity-sfcc)
- [B2C Commerce custom preferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-preferences.html)
- [B2C Commerce job framework](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-jobs.html)