Prerequisites

Before starting setup, make sure you have:

SFCC B2C Commerce instance — Sandbox or production
Business Manager admin access — For cartridge upload and site configuration
Account Manager admin access — For creating the API client (OCAPI credentials)

Setting up the OCAPI Client in Account Manager

First, you you will need to create the API client credentials that Numeral and Fivetran need to access your SFCC data.

Why This Is Needed

Numeral uses SFCC’s Open Commerce API (OCAPI) for two purposes:

Product sync — Imports your product catalog into Numeral so products can be mapped to the correct tax categories
Order data sync — Fivetran uses the same credentials to sync orders, customers, and catalog data on an ongoing basis for tax filing

Both Numeral and Fivetran share the same API client credentials. You only need to create one API client.

Step 1: Log Into Account Manager

Go to account.demandware.com
Log in with your SFCC administrator credentials

Note: You need Account Manager admin privileges to create API clients. If you don’t have access, contact your SFCC administrator.

Step 2: Create a New API Client

In Account Manager, navigate to API Client in the left sidebar
Click Add API Client

Fill in the following fields:

Field	Value
Display Name	`Numeral Integration`
Password	Generate a strong password (this is your client secret — save it securely)
Organizations	Select your organization
Roles	`Salesforce Commerce API` with the appropriate role scope
Default Scopes	See the scope list in Step 3
Token Endpoint Auth Method	`client_secret_post`

Step 3: Configure Required Scopes

The API client needs the following OCAPI scopes. These cover both Numeral’s direct usage and Fivetran’s ongoing data sync.

Roles:

Add the appropriate instance to the Salesforce Commerce API section:

Default scopes:

roles
tenantFilter
profile

Allowed scopes:

roles
tenantFilter
profile
sfcc.products
sfcc.promotions
sfcc.customerlists
sfcc.catalogs
sfcc.gift-certificates
sfcc.source-codes
sfcc.orders

Redirect URIs:

https://admin.dx.commercecloud.salesforce.com/oauth2-redirect.html

Click Save
Important: Note down the Client ID (auto-generated) and the Client Secret (the password you entered). You’ll need both when connecting in Numeral.

Warning: The client secret cannot be retrieved after creation. Store it in a secure location (e.g., a password manager). If lost, you’ll need to generate a new one.

Step 4: Configure OCAPI Settings in Business Manager

In addition to the API client, you need to configure OCAPI access rules in Business Manager to allow the client to access Shop and Data API endpoints.

Shop API Configuration

In Business Manager: Administration > Site Development > Open Commerce API Settings
Select Shop API from the dropdown
Select your Site (e.g., RefArch)
Add the following JSON configuration (replace YOUR_CLIENT_ID with your actual client ID):

{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "YOUR_CLIENT_ID",
      "resources": [
        {
          "resource_id": "/**",
          "methods": [
            "get",
            "patch",
            "post",
            "put",
            "delete"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/orders/*",
          "methods": [
            "get",
            "patch"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

Click Save

Data API Configuration

On the same page, select Data API from the dropdown
Select Global (organization-wide)
Add the following JSON configuration:

{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "YOUR_CLIENT_ID",
      "resources": [
        {
          "resource_id": "/**",
          "methods": ["get", "patch", "post", "put", "delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

Click Save

Step 5: Gather Connection Details

While you’re in Account Manager and Business Manager, gather the following values. You’ll need all of them when creating the SFCC connection in Numeral.

Detail	Where to Find It	Example
Client ID	Account Manager > API Client > your client	`cbdde83e-53cf-4e8b-813e-f286bc500c41`
Client Secret	The password you set when creating the API client	(stored securely)
Organization ID	Business Manager > Administration > Site Development > Salesforce Commerce API Settings	`f_ecom_zyur_001`
Short Code	Business Manager > Administration > Site Development > Salesforce Commerce API Settings	`kv7kzm78`
Instance Hostname	Your SFCC instance URL (without `https://`)	`zyur-001.dx.commercecloud.salesforce.com`
Site ID	Business Manager > Merchant Tools > Sites > Manage Sites	`RefArch`
Customer List ID	Business Manager > Merchant Tools > Sites > Customer Lists	`RefArch`

Finding the Customer List ID

In Business Manager: Merchant Tools > Customers > Customer Lists
The ID column shows the customer list ID
If you have multiple customer lists, select the primary one used by your storefront

Finding the Instance Hostname

Your instance hostname is the domain you use to access Business Manager, without the /on/demandware.store/... path. For example:

Full BM URL: https://zyur-001.dx.commercecloud.salesforce.com/on/demandware.store/...
Instance Hostname: zyur-001.dx.commercecloud.salesforce.com

Checklist

Before moving on, verify you have:

API client created in Account Manager with all required scopes
Client ID and Client Secret saved securely
OCAPI Shop API and Data API configured in Business Manager
All connection details gathered (Organization ID, Short Code, Instance Hostname, Site ID, Customer List ID)

Installing the Numeral Cartridge

Next, we'll walk you through installing and configuring the Numeral cartridge (plugin_numeral) on your SFCC B2C Commerce instance.

What the Cartridge Does

The Numeral cartridge adds two capabilities to your SFCC storefront:

Tax calculation at checkout — When a customer enters their shipping address, the cartridge calls the Numeral API to calculate accurate tax in real time
Transaction creation on order placement — When an order is placed, the cartridge records it as a tax transaction in Numeral for filing

Obtaining the Cartridge

The cartridge is provided as a ZIP file: numeral-sfcc-cartridge.zip

Contact your Numeral account representative to receive the latest version.

The ZIP contains:

plugin_numeral/
  cartridge/
    hooks.json                    # Hook registration
    plugin_numeral.properties     # Cartridge metadata
    controllers/
      CheckoutServices.js         # Transaction creation on PlaceOrder
    scripts/
      hooks/
        taxes.js                  # Tax calculation hook
      services/
        numeralService.js         # HTTP client for Numeral API
metadata/
  site-preferences.xml            # Numeral site preference definitions
  custom-objects.xml              # Custom attributes for Order and Basket

Step 1: Upload the Cartridge to SFCC

Upload using a WebDAV client

Important: macOS Finder mounts SFCC WebDAV as read-only and cannot upload files. You must use Cyberduck or another WebDAV client.

1. Find the WebDAV URL

In Business Manager: go to Administration > Site Development > Code Deployment
Click on the active code version link
Locate the WebDAV URL shown on this page

2. Connect with Cyberduck

Download and install Cyberduck (free for macOS and Windows)
Open Cyberduck and click Open Connection
Set the protocol to WebDAV (HTTPS)
Configure the connection:

Field	Value
Server	Your instance hostname (e.g., `zyur-001.dx.commercecloud.salesforce.com`)
Port	`443`
Path	`/on/demandware.servlet/webdav/Sites/Cartridges/YOUR_ACTIVE_CODE_VERSION`
Username	Your Business Manager email address
Password	Your Business Manager password

Close this dialog and double click to connect

3. Upload the Cartridge

Extract the numeral-sfcc-cartridge.zip file on your computer
Drag the plugin_numeral/ folder from the extracted ZIP into the active code version folder in Cyberduck

4. Verify the Upload

After upload, the folder structure should look like:

Cartridges/
  <active-version>/
    plugin_numeral/
      cartridge/
        hooks.json
        plugin_numeral.properties
        controllers/
          CheckoutServices.js
        scripts/
          hooks/
            taxes.js
          services/
            numeralService.js
    app_storefront_base/
      ...
    (other cartridges)

Step 2: Add to Cartridge Path

The cartridge path tells SFCC which cartridges are active and in what order they’re loaded.

In Business Manager: Administration > Sites > Manage Sites
Click on your site (e.g., RefArch)
Go to the Settings tab
Find the Cartridge Path field
Add plugin_numeral to the beginning of the cartridge path, separated by a colon

Before:

app_storefront_base:modules:...

After:

plugin_numeral:app_storefront_base:modules:...

Click Apply

Important: plugin_numeral must be first in the cartridge path (before any other tax-related cartridge). This ensures Numeral’s tax calculation takes priority over SFCC’s default tax tables.

Step 3: Import Metadata XML Files

The cartridge requires two metadata files to be imported. These create site preferences (for configuration) and custom attributes (for storing tax data on orders).

Import Site Preferences

In Business Manager: Administration > Site Development > Import & Export
Under the Upload section:
- Click Choose File
- Select metadata/site-preferences.xml from the extracted ZIP
- Click Upload
Under the Import section:
- Select site-preferences.xml from the list of uploaded files
- Click Import
- Confirm when prompted

This creates:

A Numeral preference group under Custom Preferences
c_numeralApiKey — Site preference for the Numeral API key
c_numeralApiBaseUrl — Site preference for the API base URL (defaults to https://api.numeralhq.com)

Import Custom Object Attributes

On the same Import & Export page:
- Upload metadata/custom-objects.xml
- Then import it

This creates custom attributes on the Order and Basket system objects:

Attribute	Type	Description
`c_numeral_tax_amount`	Number	Total tax amount calculated by Numeral
`c_numeral_calculation_id`	String	Numeral calculation ID (links to the tax calculation)
`c_numeral_transaction_id`	String	Numeral transaction ID (set after order placement)
`c_numeral_tax_calculated_at`	String	ISO 8601 timestamp of when tax was last calculated

Verify the Imports

Check site preferences:

Go to Merchant Tools > Site Preferences > Custom Preferences
You should see a Numeral group

Check custom attributes:

Go to Administration > Site Development > System Object Types
Click Order
Go to Attribute Definitions
You should see the four c_numeral_* attributes

Step 4: Configure the Numeral API Key

In Business Manager: Merchant Tools > Site Preferences > Custom Preferences > Numeral
Set the following:

Preference	Value
Numeral API Key	Your Numeral API key (`sk_test_...` for sandbox, `sk_prod_...` for production)
Numeral API Base URL	Leave as default: `https://api.numeralhq.com`

Click Save

Sandbox vs Production: Use a test API key (sk_test_...) while setting up and testing. Switch to the production key (sk_prod_...) when you’re ready to go live. The test key works the same way but marks transactions as test mode.

Step 5: Verify the Installation

Quick Test

Open your storefront in a browser
Add any item to the cart
Proceed to checkout
Enter a US shipping address (e.g., 100 Congress Ave, Austin, TX 78701)
Tax should be calculated and displayed on the order summary

Check Logs

If tax isn’t showing, check the SFCC logs:

In Business Manager: Administration > Site Development > Development Setup
Click Log Files
Look for log files with the numeral category

Check Order Attributes

After placing a test order:

In Business Manager: Merchant Tools > Ordering > Orders
Open the test order
Check the Attributes tab for:
- c_numeral_calculation_id — Should be set (e.g., calc_abc123...)
- c_numeral_transaction_id — Should be set (e.g., txn_def456...)
- c_numeral_tax_amount — Should match the tax displayed at checkout

Troubleshooting

Tax shows as $0.00

Check cartridge path: Ensure plugin_numeral is listed first in the cartridge path
Check API key: Go to Merchant Tools > Site Preferences > Custom Preferences > Numeral and verify the API key is set
Check logs: Look for error messages in the numeral log category

Tax is not calculated at all (default SFCC tax shows instead)

Check metadata import: Verify the “Numeral” preference group exists under Custom Preferences
Check hooks.json: Ensure the cartridge was uploaded correctly with the hooks.json file intact
Clear cache: In Business Manager, go to Administration > Site Development > Code Deployment and try activating the code version again

Transaction not created after order placement

Check calculation ID: The order must have c_numeral_calculation_id set (from the checkout tax calculation)
Check if already created: If c_numeral_transaction_id is already set, the transaction was already created
Check logs: Look for errors in the numeral/orderPayment log category

API errors

401 Unauthorized: The API key is invalid or expired. Check the key in Site Preferences.
Timeout: The Numeral API has a 10-second timeout. If your network is slow, the cartridge will fall back to SFCC’s default tax tables.
500 Server Error: Contact Numeral support.

Connecting SFCC in the Numeral Dashboard

This final step walks you through creating the Commerce Cloud connection in Numeral, which links your SFCC instance to the Numeral platform for tax calculation, data sync, and filing.

Prerequisites

Before starting, make sure you have completed:

You’ll need the following values (gathered in the OCAPI setup guide):

Detail	Example
Instance Hostname	`zyur-001.dx.commercecloud.salesforce.com`
Site ID	`RefArch`
Organization ID	`f_ecom_zzrf_001`
Short Code	`kv7kzm78`
Customer List ID	`RefArch`
OCAPI Client ID	`cbdde83e-53cf-4e8b-813e-f286bc500c41`
OCAPI Client Secret	(your stored secret)

Step 1: Navigate to Store Setup

Log into the Numeral Dashboard at app.numeralhq.com
Navigate to Connections
Click Add Connection
Select Salesforce Commerce Cloud as the platform

Step 2: Enter Connection Details

Fill in the connection form with the values gathered from Account Manager and Business Manager:

Field	What to Enter	Notes
Store Name	A friendly name for this connection	e.g., “My SFCC Store” or “US Storefront”
Instance Hostname	Your SFCC instance URL	e.g., `zyur-001.dx.commercecloud.salesforce.com` (without `https://`)
Site ID	Your storefront site ID	e.g., `RefArch`, `SiteGenesis`
Organization ID	Your SFCC organization ID	Found in Account Manager
Short Code	Your SFCC short code	Found in BM under Salesforce Commerce API Settings
Customer List ID	Your customer list ID	Found in BM under Merchant Tools > Customers > Customer Lists
OCAPI Client ID	API client ID	From Account Manager
OCAPI Client Secret	API client secret/password	From Account Manager

Step 3: Validate and Connect

Click Connect (or Save)
Numeral will validate your OCAPI credentials by attempting to authenticate against SFCC
- If successful, the connection is created
- If authentication fails, double-check your Client ID, Client Secret, and Instance Hostname

Step 4: Finish Setup

After the connection is validated:

Click Finish Setup
Numeral will automatically:
- Create a Fivetran connector to sync your SFCC data (orders, products, customers, catalogs)
- Import all your SFCC products into Numeral with a default tax category of “General Merchandise”
- Generate API keys for the Numeral cartridge

This process typically takes 2–5 minutes.

Step 5: Get Your API Keys

After setup completes, Numeral generates two API keys:

Key	Format	Purpose
Production API Key	`sk_prod_...`	For your production storefront
Test API Key	`sk_test_...`	For sandbox/testing (transactions marked as test)

On the connection details page, locate the API Keys section
Copy the appropriate key
Go to SFCC Business Manager and enter the key in Merchant Tools > Site Preferences > Custom Preferences > Numeral > Numeral API Key (see Cartridge Installation, Step 4)

Tip: Use the test key (sk_test_...) while verifying the setup. Switch to the production key (sk_prod_...) when you’re ready to go live.

What Happens Behind the Scenes

When you finish setup, Numeral orchestrates several automated processes:

1. Fivetran Connector Creation

A Fivetran connector is created with the salesforce_commerce_cloud service type. It’s configured to sync the following data from your SFCC instance:

Data Type	Tables Synced
Orders	`order`, `order_product_line_item`, `order_shipment`, `order_payment_instrument`, `price_adjustment`
Products	`product`
Catalogs	`catalog`
Customers	`customer`, `customer_address`

The connector syncs every 60 minutes and sends data to Numeral’s data warehouse for processing.

2. Product Import

All products in your SFCC catalog are imported as Client Products in Numeral. Each product is assigned the default tax category of “General Merchandise”. You’ll map products to their correct tax categories in the next step.

3. API Key Generation

Two API keys (production and test) are generated and linked to this connection. These keys authenticate the cartridge when it calls the Numeral API.

Multiple Sites / Multiple Connections

If you have multiple SFCC sites (e.g., different brands or regions), you need a separate connection for each site:

Each site has its own Site ID, and may have different products and tax rules
Each connection gets its own API keys
Each connection creates its own Fivetran connector
The cartridge must be configured

Using Numeral's Tax Engine with Salesforce Agentforce Commerce (formerly Salesforce Commerce Cloud)

Prerequisites

Setting up the OCAPI Client in Account Manager

Why This Is Needed

Step 1: Log Into Account Manager

Step 2: Create a New API Client

Step 3: Configure Required Scopes

Roles:

Default scopes:

Allowed scopes:

Redirect URIs:

Step 4: Configure OCAPI Settings in Business Manager

Shop API Configuration

Data API Configuration

Step 5: Gather Connection Details

Finding the Customer List ID

Finding the Instance Hostname

Checklist

Installing the Numeral Cartridge

What the Cartridge Does

Obtaining the Cartridge

Step 1: Upload the Cartridge to SFCC

Upload using a WebDAV client

1. Find the WebDAV URL

2. Connect with Cyberduck

3. Upload the Cartridge

4. Verify the Upload

Step 2: Add to Cartridge Path

Step 3: Import Metadata XML Files

Import Site Preferences

Import Custom Object Attributes

Verify the Imports

Step 4: Configure the Numeral API Key

Step 5: Verify the Installation

Quick Test

Check Logs

Check Order Attributes

Troubleshooting

Tax shows as $0.00

Tax is not calculated at all (default SFCC tax shows instead)

Transaction not created after order placement

API errors

Connecting SFCC in the Numeral Dashboard

Prerequisites

Step 1: Navigate to Store Setup

Step 2: Enter Connection Details

Step 3: Validate and Connect

Step 4: Finish Setup

Step 5: Get Your API Keys

What Happens Behind the Scenes

1. Fivetran Connector Creation

2. Product Import

3. API Key Generation

Multiple Sites / Multiple Connections