Platform Contracts and ConnectWise Agreements

Introduction

When invoice lines are synced from the Platform to ConnectWise, each line must be attached to a ConnectWise Agreement. On the Platform side, invoice lines belong to an Invoice Contract. These two concepts — Platform Invoice Contract and ConnectWise Agreement — serve a similar purpose (defining the billing relationship with a customer) but they are not the same thing, they exist in different systems, and they do not have a strict one-to-one relationship.

This article explains what each concept is, how they are linked during the integration, and what Partners need to be aware of when managing both systems.

1. What is a Platform Invoice Contract?

In the Platform, a Contract is the agreement that defines the billing relationship between two organizations. There are three contract purposes — Invoice, Resell, and Consume. For the ConnectWise integration, only the Invoice Contract is relevant.

An Invoice Contract is created between a Seller (Provider) and a Customer (Consumer). It defines:

• Billing Cycle Day — the day of the month (1–28) when invoices are generated for that Customer
• Currency — the currency used for all invoice lines under this contract
• Contract Type — for example, Distribution Services, CSP, Azure Plan & OneTime

The Invoice Contract is created automatically when a Customer is onboarded on the Platform. Partners do not normally need to create or modify Invoice Contracts — the key attributes to be aware of for the integration are the Currency and the Contract ID.

2. What is a ConnectWise Agreement?

In ConnectWise, an Agreement is the billing container that invoice lines (Additions) are attached to. It defines the billing terms for a specific Company — billing cycle, currency, and invoicing settings. When the Platform syncs invoice lines to ConnectWise, they appear as Additions on the Agreement for the mapped Company.

Key Agreement fields that matter for the integration:

ConnectWise Agreement Details:

3. The key difference: one Agreement per Company

The most important concept to understand about how the integration manages Agreements is the one Agreement per Company rule:

This means the relationship between Platform contracts and ConnectWise Agreements is many-to-one:

In practice this means: if a Customer has both a Distribution Services contract and a CSP contract on the Platform, all invoice lines from both contracts land as Additions under the single Agreement for that Company in ConnectWise. Partners do not need to create separate Agreements per contract type.

4. How the Contract → Agreement mapping is established

The integration stores a mapping record linking each Platform Contract to a ConnectWise Agreement. This mapping is established automatically during the Load phase (when you click Load Invoices) and resolved again during Sync if the mapping was not set during load. Partners can also assign it manually on the Invoices tab.

The resolution follows this order:

5. What an auto-created Agreement looks like in ConnectWise

When the integration creates a new Agreement in ConnectWise (Step 4 above), it sets the following fields:

6. Currency: how it flows from Contract to Agreement

Currency is one of the most important alignment points between Platform contracts and ConnectWise Agreements. A mismatch causes invoice lines to be posted in the wrong currency — ConnectWise does not convert currencies automatically and does not warn about mismatches.

Before syncing invoice lines for a Customer, verify that the Currency shown in the Platform's Mapping → Invoices tab matches the Currency set on the ConnectWise Agreement for that Company.

7. Changing the Contract → Agreement mapping

Partners can change which ConnectWise Agreement a Platform contract's invoice lines are posted to by editing the PSA Agreement Name on the Invoices tab. This can be done per line using the edit (pencil) icon, or across multiple lines using Bulk Update.

What happens automatically

When the PSA Agreement Name is changed for one invoice line, the new mapping is automatically applied to all other Not Synced and Failed lines that share the same Contract ID and Organization. You do not need to update each line individually — the cascade handles it.

Before the edit:

One line edited:

After the sync:

NOTE! The cascade only affects lines with Status in PSA = Not Synced or Failed. Lines that are already Synced are not affected — they remain on the original Agreement in ConnectWise.

What requires manual action in ConnectWise

When a Contract → Agreement mapping is changed, the integration does not automatically cancel or move the Additions that were previously synced to the old Agreement. Those Additions remain open in ConnectWise and will continue to appear on invoices until manually cancelled.

talog. 

Warning! After changing a PSA Agreement Name for a contract that already has Synced lines, you must manually clean up ConnectWise to avoid double billing. The required steps are:

1. In ConnectWise, navigate to Finance → Agreements → open the old Agreement → Additions tab.

2. For each Addition that was created by the integration for the affected subscriptions, manually set a Cancelled Date to stop them from billing further. The Cancelled Date should be set to the last day of the final billing period you want to include on the old Agreement.


3. Return to the Platform's Mapping → Invoices tab and re-sync the affected invoice lines. They will now be created as new Additions under the new Agreement.

Summary

Platform Invoice Contracts and ConnectWise Agreements serve similar purposes — defining the billing relationship with a customer — but they are different objects in different systems. The key points to remember:

• The Invoice Contract on the Platform defines the Customer's billing currency and billing cycle day. Its Contract ID appears on the Mapping → Invoices tab and identifies which contract each invoice line belongs to.
• ConnectWise uses one Agreement per Company for all Platform contracts related to that Company. Multiple Platform contracts for the same Customer all post to the same Agreement.
• The Contract → Agreement mapping is established automatically during Load and Sync — the integration searches ConnectWise for an Agreement matching the configured Agreement Type name, and creates one if none is found.
• When a new Agreement is created automatically, its Start Date is the first day of the charge start month, its Billing Cycle is Monthly, and proration is enabled immediately.
• The Platform Invoice Contract's Currency must match the ConnectWise Agreement's Currency. Mismatches post values in the wrong currency without warning.
• Changing the PSA Agreement Name for a contract cascades to all Not Synced and Failed lines for that contract automatically, but does not cancel previously synced Additions on the old Agreement — that cleanup must be done manually in ConnectWise.

Related articles

• Understanding contract types in the Platform — full explanation of Invoice, Resell, and Consume contract purposes
• Setting up the ConnectWise integration — how to configure the Agreement Type in Platform Settings
• ConnectWise integration: Mapping organizations and products — how Organization mapping links Platform customers to CW Companies
• ConnectWise integration: Loading and syncing invoice lines — how to set PSA Agreement Name on the Invoices tab
• Invoice lines in ConnectWise Manage — where to find Additions on Agreements in ConnectWise
• Charge-date rules: how they affect Additions in ConnectWise — how Agreement Billing Start Date affects Effective Dates
• ConnectWise Setup Guide for Partners — CW-side configuration including Agreement Types and currency setup