> ## 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.

# Salesforce Sales Cloud

> Automated tax calculation on Salesforce Quotes and Orders with transaction filing.

This guide walks Salesforce admins and sales ops teams through connecting Salesforce Sales Cloud to Numeral for automated tax calculation. Once set up, tax is calculated and filed automatically on Quotes and Orders — no manual entry required.

## Prerequisites

* System Administrator access to a Salesforce org (Enterprise edition or higher)
* Quotes and Orders enabled in Salesforce
* Access to the Numeral dashboard at [numeralhq.com](https://numeralhq.com)

***

## Part A — Connect Salesforce in the Numeral Dashboard

This step generates the API key your Salesforce org will use to authenticate with Numeral.

1. Log in to the Numeral dashboard and click **Connections** in the left sidebar
2. Click **Add Connection** and select **Salesforce Sales Cloud**
3. Numeral automatically generates a unique API key for your org
4. Click **Install Numeral Tax Package** — this opens the Salesforce package installer in a new tab (complete Part B below before returning)
5. Click **Copy API Key** — the key is copied to your clipboard
6. After completing Parts B and C, return to this dialog and click **Finish Connection**

<Note>
  Keep this browser tab open while you complete the Salesforce steps below.
</Note>

### Authorize Fivetran Data Sync

Numeral uses Fivetran to sync your Salesforce data for reporting and filing. This is a one-time step completed in the Numeral dashboard.

1. Click **Continue to Fivetran** — you will be redirected to Fivetran to authorize access to your Salesforce org
2. Complete the Fivetran authorization — you will be redirected back to Numeral automatically

Once authorized, Numeral will begin syncing Opportunities, Orders, Products, and related records on a daily basis. Allow up to 24 hours for the initial sync to complete.

***

## Part B — Install and Configure in Salesforce

### Step 1 — Install the package

Use the **Install Numeral Tax Package** link from the Numeral dashboard connection dialog (Part A, step 4) — this always points to the latest released version. When prompted, select **Install for Admins Only** and click **Install**. Salesforce will send a confirmation email when installation is complete (usually a few minutes).

### Step 2 — Configure the connection

1. In Salesforce, click the **App Launcher** (the 9-dot grid in the top-left) and search for **Numeral Tax Setup**
2. Open the **Numeral Tax Setup** tab
3. Fill in the following fields:
   * **Numeral API URL** — leave the pre-filled default value as-is unless Numeral support has given you a different URL
   * **Numeral API Key** — paste the key you copied from the Numeral dashboard
   * **Test Mode** — turn **On** for sandbox or UAT orgs; turn **Off** for production
4. Click **Save Settings**
5. Click **Test Connection** — the status badge should turn green and show **Connected**

If the badge shows **Invalid**, your API key may have been copied incorrectly. Return to the Numeral dashboard, copy the key again, and repeat from step 3.

***

## Part C — Add the Tax Panel to Record Pages

The Numeral Tax panel must be added to your Quote and Order record pages using Lightning App Builder. Repeat these steps for both object types.

**For Quotes:**

1. Open any Quote record
2. Click the **gear icon** (⚙) in the top-right → **Edit Page**
3. In the component panel on the left, scroll down to find **Numeral Tax** under Custom components
4. Drag it onto the page — the right-hand column below the highlights panel is recommended
5. Click **Save**, then **Activate**
6. In the activation dialog, select the profiles and apps this layout should apply to, then click **Assign as Org Default** (or scope to specific apps/profiles as needed)

**For Orders:**

Repeat the same steps on any Order record.

<Note>
  **Mobile (optional):** If your team uses the Salesforce mobile app, repeat the above steps and select the **Phone** form factor for each record page.
</Note>

***

## Part D — Verify the Setup

1. Create or open a **Quote** that has at least one line item and a shipping address
2. Save the Quote — the Numeral Tax panel should show **Calculated** with a tax amount within a few seconds
3. Check that the native **Tax** and **Grand Total** fields on the Quote have updated automatically
4. Create or open an **Order** with a shipping address — tax calculates on save
5. **Activate** the Order — the tax panel should change to **Committed**, indicating the tax has been sent to Numeral for filing

***

## How It Works Day-to-Day

Once configured, everything runs automatically:

| Salesforce action                         | What Numeral does                                            |
| ----------------------------------------- | ------------------------------------------------------------ |
| Quote saved or shipping address changed   | Recalculates tax estimate                                    |
| Order created or shipping address changed | Calculates tax estimate                                      |
| Order activated                           | Commits tax transaction for filing                           |
| Activated Order moved back to Draft       | Voids the committed transaction; calculates a fresh estimate |
| Order cancelled                           | Voids the tax transaction                                    |

Tax amounts and statuses on the record update in real time — no page reload needed.

***

## Tax Panel Status Reference

| Status         | Meaning                                      |
| -------------- | -------------------------------------------- |
| **Pending**    | Calculation is in progress                   |
| **Calculated** | Tax has been estimated; not yet filed        |
| **Committed**  | Tax is locked and sent to Numeral for filing |

**Recalculate Tax button:** This button appears on Quotes and Draft Orders when the tax estimate may be stale (for example, after a price change). It is hidden on Activated Orders because committed transactions cannot be modified — deactivate the Order first if changes are needed.

<Note>
  Tax calculation IDs expire after 24 hours. If you create an Order and activate it more than 24 hours later, click **Recalculate Tax** on the Order before activating to refresh the estimate.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test Connection shows &#x22;Invalid&#x22;">
    The API key is incorrect or was not pasted completely. Go back to the Numeral dashboard, copy the key again, re-paste it into the Numeral Tax Setup tab, save, and test again.
  </Accordion>

  <Accordion title="Tax panel is not visible on a Quote or Order record">
    The component has not been added to that record page, or the page has not been activated for your profile. Repeat the App Builder steps in Part C and confirm the activation includes your profile.
  </Accordion>

  <Accordion title="Tax shows $0 or is not updating">
    The Quote or Order is missing a shipping address. Salesforce requires a ship-to address to determine the correct tax jurisdiction. For Orders without a shipping address, the Account's billing address is used as a fallback — ensure that is also populated.
  </Accordion>

  <Accordion title="Tax panel shows an error after the Order was committed">
    An activated Order cannot be recalculated. To make changes, deactivate the Order (move it back to Draft) — this automatically voids the committed transaction and recalculates a fresh estimate. You can then make edits and re-activate.
  </Accordion>

  <Accordion title="Connection shows Connected but tax is not calculating">
    Confirm Test Mode is set correctly for your environment (On for sandbox, Off for production). Also verify that the Numeral Tax panel has been added to the record page and activated — it will not appear on records until the App Builder steps in Part C are complete.
  </Accordion>
</AccordionGroup>