What is a custom object type in SFCC?

Custom object types are developer-defined data structures stored in the B2C Commerce database. They are the standard pattern for app configuration, processing queues, external sync state, and any data that does not fit the standard commerce objects. Each instance is scoped to either a site or the entire organization.

What is the difference between site-scoped and organization-scoped?

Site-scoped objects are isolated per storefront site — useful for per-site configuration or queues. Organization-scoped objects are shared across all sites in the realm — useful for global configuration or cross-site data like a shared email subscription list.

What is the key attribute?

The key attribute is the primary key for the custom object type. It must be unique within the scope. You can choose string, int, or datetime as the key type. If auto-generated is true, the platform generates a unique key on creation; otherwise your code must supply it.

How do I import the generated XML?

Place the file at sites/site_template/meta/custom-objecttype-definitions.xml inside a site archive zip, then import via Business Manager > Administration > Site Development > Site Import & Export, or use the SFCC CLI: sf commerce:site:import.

Can I add attributes to an existing custom object type?

Yes — re-import the XML with the new attributes added. Existing instances are not affected; the new attributes will be null until populated. You cannot change the type of an existing attribute or remove the key attribute.

Custom Object Type XML Builder

Generate custom-objecttype-definitions.xml for SFCC site archives — the standard pattern for app config, queues, and external sync state.

Type ID

Display name

Description (optional)

Storage scope

Key type

Key attribute id

Auto-generate key

Attributes

Definition valid — XML ready

Generated XML

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <custom-type type-id="EmailSubscription">
        <display-name xml:lang="x-default">Email Subscription</display-name>
        <description xml:lang="x-default">Email opt-in records imported from external systems</description>
        <storage-scope>site</storage-scope>
        <key-definition attribute-id="email">
            <type>string</type>
            <mandatory-flag>true</mandatory-flag>
            <auto-generated-flag>false</auto-generated-flag>
        </key-definition>
        <attribute-definitions>
            <attribute-definition attribute-id="firstName">
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="subscribedAt">
                <type>datetime</type>
                <mandatory-flag>true</mandatory-flag>
            </attribute-definition>
            <attribute-definition attribute-id="preferences">
                <type>set-of-string</type>
                <value-definitions>
                    <value-definition>
                        <display xml:lang="x-default">Daily</display>
                        <value>daily</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Weekly</display>
                        <value>weekly</value>
                    </value-definition>
                </value-definitions>
            </attribute-definition>
        </attribute-definitions>
    </custom-type>
</metadata>

About Custom Object Type XML Builder

Generate custom-objecttype-definitions.xml for SFCC site archives. Define the key attribute, storage scope, and typed fields — then import via Business Manager or the CLI. The builder validates your definition before generating XML so you catch naming errors and missing enum values before the import fails.

Pipeline

SFCC Site Import Analyzer — inspect the archive that contains this XML.
XML / JSON Converter — convert the generated XML to JSON for review.

Frequently asked

What is a custom object type in SFCC?: Custom object types are developer-defined data structures stored in the B2C Commerce database. They are the standard pattern for app configuration, processing queues, external sync state, and any data that does not fit the standard commerce objects. Each instance is scoped to either a site or the entire organization.
What is the difference between site-scoped and organization-scoped?: Site-scoped objects are isolated per storefront site — useful for per-site configuration or queues. Organization-scoped objects are shared across all sites in the realm — useful for global configuration or cross-site data like a shared email subscription list.
What is the key attribute?: The key attribute is the primary key for the custom object type. It must be unique within the scope. You can choose string, int, or datetime as the key type. If auto-generated is true, the platform generates a unique key on creation; otherwise your code must supply it.
How do I import the generated XML?: Place the file at sites/site_template/meta/custom-objecttype-definitions.xml inside a site archive zip, then import via Business Manager > Administration > Site Development > Site Import & Export, or use the SFCC CLI: sf commerce:site:import.
Can I add attributes to an existing custom object type?: Yes — re-import the XML with the new attributes added. Existing instances are not affected; the new attributes will be null until populated. You cannot change the type of an existing attribute or remove the key attribute.