Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.numeral.com/llms.txt

Use this file to discover all available pages before exploring further.

The Numeral cartridge for Salesforce B2C Commerce (SFCC) calculates tax during checkout and records each completed order as a transaction in Numeral. Setup has three phases:
  1. Create an OCAPI client in Account Manager so Numeral can sync your catalog and orders
  2. Install the plugin_numeral cartridge on your storefront
  3. Connect your SFCC instance to Numeral and validate the integration
This integration requires Business Manager admin access, Account Manager access, and a WebDAV client (Cyberduck recommended).

​
Phase 1 — Configure the OCAPI client

​
1. Sign in to Account Manager

Go to account.demandware.com and sign in with your administrator credentials. Account Manager login

​
2. Add an API client

Under API Client, click Add API Client. Use Display Name Numeral Integration. Add API client

​
3. Configure the API client

Set the following fields:
  • Token Endpoint Auth Method: client_secret_post
  • Access Token Format: JWT
  • Default Scopes: leave blank
  • Allowed Scopes:
    • sfcc.products
    • sfcc.promotions
    • sfcc.customerlists
    • sfcc.catalogs
    • sfcc.gift-certificates
    • sfcc.source-codes
    • sfcc.orders
API client form

​
4. Assign roles

Assign the API client the Salesforce Commerce API and Sandbox API User roles, scoped to the organization that owns your storefront. API client roles

​
5. Set the redirect URI

Add this redirect URI: 
https://admin.dx.commercecloud.salesforce.com/oauth2-redirect.html
Redirect URIs

​
6. Configure OCAPI Shop API and Data API

In Business Manager → Administration → Site Development → Open Commerce API Settings, paste the JSON configuration provided by Numeral for both Shop API and Data API contexts. Shop API config Data API config

​
7. Capture the connection details

Save the seven values you’ll provide to Numeral:
ValueWhere to find it
Client IDAccount Manager → API Client
Client SecretAccount Manager → API Client (shown once)
Organization IDBusiness Manager → Administration → Site Development → Salesforce Commerce API Settings
Short CodeSame screen as Organization ID
Instance HostnameThe host portion of your Business Manager URL
Site IDBusiness Manager → Administration → Sites → Manage Sites
Customer List IDBusiness Manager → Administration → Sites → Customer Lists
Connection details — page 1 Connection details — page 2

​
Phase 2 — Install the cartridge

​
1. Connect to WebDAV

The plugin_numeral cartridge is delivered as a zip. You’ll upload it to your sandbox via WebDAV. Find your WebDAV URL in Business Manager under Administration → Site Development → Development Setup. WebDAV details WebDAV details
macOS Finder mounts WebDAV in read-only mode. Use Cyberduck (free, macOS/Windows) or another WebDAV client that supports writes.

​
2. Connect with Cyberduck

In Cyberduck, create a new bookmark with WebDAV (HTTPS), the host portion of your sandbox URL, and your Business Manager username/password. Cyberduck connection

​
3. Upload the cartridge

Navigate to /Cartridges/{your-version-number}/ and upload the plugin_numeral folder from the cartridge zip Numeral provided. Upload cartridge

​
4. Update the cartridge path

In Business Manager → Administration → Sites → Manage Sites → {your site} → Settings, prepend plugin_numeral to the Cartridges path so it loads first: 
plugin_numeral:app_storefront_base:...
plugin_numeral must appear before app_storefront_base in the cartridge path. If it appears later, the storefront will not invoke Numeral’s checkout hooks.
Cartridge path

​
5. Import the metadata

The cartridge zip includes two metadata files: site-preferences.xml and custom-objects.xml. Import both via Administration → Site Development → Site Import & Export. Import step 1 Import step 2 Import step 3 Import step 4 Import step 5 The import creates the following site preferences:
PreferencePurpose
c_numeralApiKeyYour Numeral API key
c_numeralApiBaseUrlNumeral API base URL (e.g. https://api.numeralhq.com)
And these custom attributes on the Order system object:
  • c_numeral_tax_amount
  • c_numeral_calculation_id
  • c_numeral_transaction_id
  • c_numeral_tax_calculated_at
Verify site preferences Verify order custom attributes

​
Phase 3 — Connect to Numeral

​
1. Configure the API key in SFCC

Set c_numeralApiKey and c_numeralApiBaseUrl under Merchant Tools → Site Preferences → Custom Preferences → Numeral. API key configuration

​
2. Run a quick checkout test

Place a test order on your sandbox storefront. Confirm tax appears on the order summary. Quick test

​
3. Inspect the logs

In Business Manager, go to Administration → Site Development → Custom Log Settings to view the Numeral request and response payloads. Confirm there are no errors. Logs

​
4. Verify the order’s custom attributes

Open the order in Business Manager and confirm the four c_numeral_* custom attributes are populated. Order custom attributes

​
5. Add the connection in Numeral

In your Numeral dashboard under Settings → Integrations → Salesforce Commerce Cloud, click Add Connection and provide the seven values you captured in Phase 1. Numeral connections Numeral will validate the credentials, sync your catalog as General Merchandise, and provision a Fivetran connector for ongoing sync.

​
6. Generate API keys

Numeral generates a sk_test_* API key for your sandbox. Once you’re ready for production, generate a sk_prod_* key and update c_numeralApiKey in your production site preferences. API keys
If you operate multiple sites or storefronts, create a separate Numeral connection per site so each site has its own API key and transaction history.

​
Troubleshooting

Confirm plugin_numeral is the first entry in the cartridge path and the API key in c_numeralApiKey matches the environment (test vs. production). Check Custom Log Settings for HTTP errors.
macOS Finder mounts WebDAV read-only. Use Cyberduck instead. Confirm your Business Manager user has WebDAV file access enabled.
Verify all seven scopes are listed under Allowed Scopes on the API client and that the OCAPI Shop API and Data API JSON configs have been imported in Business Manager.
The cartridge writes attributes only after a successful tax calculation. If logs show a calculation error (timeout, network issue, invalid address), the attributes will not populate.