Configure credentials and rules for an integration

This window is the control panel for each integration you connect to BillingBot (Pax8, Ingram Micro, Ingram CloudBlue, ITCloud, Twilio, HaloPSA, or AutoTask). Here you enter the access credentials, verify that they work, and define how BillingBot should handle that integration's products and invoices.

When to use this screen

• When you add a new integration and need to enter its credentials for the first time.
• When an integration stopped syncing and you suspect its credentials expired or changed.
• When you want to adjust an integration's billing rules: how new products are created, how lines are grouped on invoices, or whether invoices are created new or added to an existing one.
• When you turn automatic invoice processing on or off for a distributor.

What it shows

The window opens as a dialog called "Integration Settings" and is organized into blocks that appear depending on the integration type:

• API Credentials: the fields vary by provider.
  • HaloPSA: Agent URL, Client ID, and Client Secret.
  • Ingram Micro: Customer Number, Client ID, and Client Secret.
  • ITCloud: Integration Key and RSA Private Key.
  • AutoTask: API Username, API Secret, API Integration Code, and a Zone URL that fills in automatically when you test the connection.
  • Ingram Cloud Blue: Username, Password, Subscription Key, and Region Code (us, ca, eu, ap, au).
  • Pax8 / Twilio: Client ID and Client Secret (if your account does not use Pax8's OAuth2 login, see Authorize Pax8 with OAuth2).
• Default Account Settings (not shown if you use AutoTask): default accounting settings — Default Accounts Code, Default Expense Code, Default Tax Code, and Default Item Code — used when a product has no specific account assigned.
• Default AutoTask Product and Default Billing Code (only if you use AutoTask): default product and billing code loaded directly from AutoTask.
• Product Lifecycle Management: a toggle to enable product management and, if enabled, three options for what to do with new or unmapped products.
• Invoice Modifiers (Pax8 and ITCloud only): checkboxes to control Azure lines, prorations, and zero-dollar lines, plus the automatic invoice processing toggle.
• Global Invoice Behavior (not shown with AutoTask): how invoices are created in HaloPSA (new, added to the latest one, or added to the recurring invoice).
• Other Integration Settings (not shown with AutoTask): option to update line descriptions when adjusting quantities.

These configuration blocks appear only after you successfully test the connection ("Test Connection"); before that, you only see the credential fields.

Available actions

• Test Connection: validates the entered credentials against the provider. If they are correct, it locks the credential fields and reveals the rest of the configuration sections.
• Modify Credentials: unlocks the credential fields so you can change them. If the integration is Pax8 with OAuth2 enabled, it also opens a new tab to authorize the account (see Authorize Pax8 with OAuth2).
• Load Products from AutoTask (AutoTask only): fetches the product list from your AutoTask account so you can choose the default product.
• Load Billing Codes from AutoTask (AutoTask only): fetches the billing codes (tax categories) available in AutoTask.
• Manage Product Lifecycles toggle: enables automatic management of products/items in your PSA.
• Options for handling new products (only if the toggle above is enabled):
  • "Prompt me to manually reconcile...": asks you to manually confirm each new or unmapped product.
  • "Automatically use the default item code...": always uses the default item you configured.
  • "Create items...automatically...": creates the product directly in your PSA using the default accounts. ⚠️ Creates new items in your PSA without asking for confirmation each time.
  • How a product finds its item. Before applying any of these options, BillingBot looks in your PSA for an item that is the product: the same SKU, or the same name (ignoring capitals, punctuation and spacing), or a name that is almost identical and has exactly the product's words (an "NCE" marker is ignored). A product that differs by a word (for example "with Copilot", "Non-Profit Pricing", "EDU", "Trial" or "Standard" instead of "Premium") is a different product and is not linked to the similar item. Only when no item is the product does the option you chose apply: the item is created, the default item is used, or the product stays unmapped until you assign it in Map Products. The same rule applies on every later sync to products that are still unmapped, so turning "Create items...automatically..." on creates the items of products that were left unmapped. A product that already has an item is never matched again; if its Accounts ID is empty, BillingBot reads it from the item it is mapped to.
• Invoice Modifiers checkboxes (Pax8/ITCloud): Drop Azure Lines, Collapse Azure Lines, Include Azure Reserved Instances, Drop Favorable Prorata, Drop Zero Dollar Lines. ⚠️ These checkboxes permanently remove or merge invoice lines before sending it to your PSA; review their description (info icon) carefully before enabling them.
• Enable Automatic Invoice Processing: enables automatic polling for new invoices from the distributor several times a day and processes them without manual intervention. ⚠️ Only applies to companies and invoices already mapped, but once enabled, invoices are sent to your PSA without prior review.
• Disable Line Grouping and Line Group Header Description: control whether lines are grouped under a header and what text that header carries.
• Global Invoice Behavior options (not AutoTask): choose whether invoices are created new, added to the latest invoice, or added to the recurring invoice in HaloPSA.
• Update/Overwrite Line Descriptions When Adjusting Quantities: in addition to adjusting quantities, also overwrites the existing line's description.
• Cancel: closes the dialog without saving changes.
• Save Settings: saves all of the integration's configuration.

Step-by-step flow

1. Open the Integrations screen and choose to add a new integration or edit an existing one so this dialog opens.
2. Fill in the credential fields for the provider (for example, Client ID and Client Secret for Pax8, or Agent URL/Client ID/Client Secret for HaloPSA).
3. Click Test Connection. If the provider is Ingram Micro, you must first enter the Customer Number.
4. If the test succeeds, you'll see the message "Credential [name] test successful!" and the additional configuration sections will appear.
5. Define the default accounts (Default Accounts Code, Expense Code, Tax Code, Item Code) or, if you use AutoTask, load the default product and billing code with the corresponding buttons.
6. If you want BillingBot to manage products automatically, enable Manage Product Lifecycles and choose one of the three handling options.
7. If the integration is Pax8 or ITCloud, review the Invoice Modifiers checkboxes and decide whether to enable automatic invoice processing.
8. If you do not use AutoTask, define the invoicing behavior (new, latest, or recurring) and whether you want to overwrite line descriptions.
9. Click Save Settings. You'll see the message "Saving Settings" while it processes and then the confirmation "Settings have been updated."
10. If you need to correct credentials later, open this screen again and use Modify Credentials.

Common errors and how to resolve them

• "Customer number is necessary!!": you tried to save an Ingram Micro integration without entering the Customer Number. Fill it in before saving.
• "!Error. Invalid Data" when testing the connection: the entered credentials are not valid for that provider. Verify that you correctly copied the Client ID/Secret or the corresponding key.
• "All AutoTask credential fields are required (Username, Secret, Integration Code).": one of the three AutoTask fields is missing before testing the connection.
• "Failed to connect to AutoTask. Check your credentials.": AutoTask rejected the credentials while trying to obtain the zone; check the Username, Secret, and Integration Code.
• "AutoTask connection test failed.": the zone connection worked but the final connection test failed; try again or confirm that your AutoTask account has API permissions.
• "Failed to load AutoTask products." / "Failed to load AutoTask billing codes.": the list could not be fetched from AutoTask; try again with Load Products from AutoTask or Load Billing Codes from AutoTask.
• "Failed to modify credentials": a problem occurred while enabling credential editing; reload the screen and try again with Modify Credentials.
• Generic error message referencing an error log: if you see a message mentioning an unexpected error while saving, note the message and report it to support; BillingBot has already saved the technical detail internally.
• "Settings have been updated.": this is not an error, it is the confirmation that your changes were saved successfully.

Related screens

• Integrations
• Authorize Pax8 with OAuth2
• Companies
• Pax8 to Halo product mapping