> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# SalesBricks Integration

> Provision usage-based deals in Paid automatically when orders close in SalesBricks.

Connect Paid to SalesBricks and every closed-won usage deal provisions automatically: the customer is created or updated, the order is activated with the deal's prices, and the deal's credits are granted. Paid polls your SalesBricks account about once a minute, so there is nothing to trigger after a deal closes.

The integration is read-only on the SalesBricks side. Paid never changes anything in your SalesBricks account.

## Prerequisites

You will need:

* A SalesBricks API key for your seller account.
* An admin user on Paid.
* A Paid product that models your usage deal, set up as described below.

## How a deal maps into Paid

The SalesBricks order is authoritative on what was sold. Paid reads the deal-authored numbers from the order and places them on the Paid product's attributes by role. Everything else about the deal (the usage meter, its rate card, the credit conversion) comes from your Paid product catalog. Because every charge comes from the deal, the Paid order total matches the SalesBricks grand total.

### Fields Paid reads

| SalesBricks field                                          | Lands in Paid as                                                                                                                                     |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Buyer `externalId`                                         | The `externalId` of the Paid customer the order belongs to                                                                                           |
| Usage brick `code`                                         | The Paid product whose `externalId` matches                                                                                                          |
| Usage line `preCommitment` (or `quantity` on older orders) | Sold credits, granted and billed                                                                                                                     |
| Usage line `includedQuantity`                              | Included credits, granted at no charge                                                                                                               |
| Usage line `netRate`                                       | Per-credit price of the sold credits                                                                                                                 |
| Usage line `overageUnitPrice`                              | Overage rate on the credit benefit and every usage meter, overriding the catalog; a fractional rate is kept exactly when sub-cent pricing is enabled |
| Subscription line `netRate` × `quantity`                   | Platform price per billing period on the recurring attribute                                                                                         |
| One-time lines `grandTotal`, summed                        | One-time fee on the one-time attribute                                                                                                               |
| Order billing schedule, start and end dates                | Billing frequency and term of the Paid order                                                                                                         |
| Order currency                                             | Currency of the Paid order; the product needs price points in it                                                                                     |

### Customer identity

The order lands on the Paid customer your signals already use. Set the buyer's external id in SalesBricks to the customer id your signals send, and the deal attaches to that customer:

* If Paid already has a customer with that `externalId`, including a draft customer created when its first signal arrived, the order goes on it and the customer becomes active.
* Otherwise Paid creates an active customer with that `externalId`, and later signals for it rate against the order.

The buyer's external id is the only identity Paid uses. The CRM account id and the SalesBricks company id are ignored, so a deal never creates a second customer that your signals do not reach. An order whose buyer has no external id is rejected.

A buyer whose signals arrive under several customer ids, one per environment or sub-entity, lists them all in its external id, separated by commas or spaces:

```
01a0ea66-5c3a-7bfb-89b4-d3ebe619cec8, 019a93a6-458d-73d0-ae13-b17f09ec7ac3
```

The first id is the customer's `externalId`. Each further id becomes an alias of that customer once the order is provisioned (the same aliases the customer alias endpoints create), so signals carrying any of the ids resolve to the one customer and rate against its order. An id that already belongs to another customer in Paid, including a draft created when a signal arrived under it, rejects the order until the id is removed from the buyer or freed in Paid.

### Fields Paid ignores

* **CRM account and SalesBricks company ids.** The buyer's external id alone identifies the customer.
* **List prices** (`unitPrice`) when a net rate is present. Deal discounts always carry through; the list price only shows the discount in the sync log.
* **Brick type** (`ADDON` or `INCLUDED`). It is recorded in the sync log, but whether a credit is sold or included comes from which quantity field carries it.
* **One-time line prices and quantities.** Only each line's post-discount `grandTotal` is billed.
* **Catalog prices of the recurring and one-time attributes.** The deal's numbers replace them on every order.

### Sold and included credits

A deal can grant two kinds of credits, and both are authored for the whole term of the order:

* **Sold credits** are the usage line's pre-commitment. They bill at the line's per-credit net rate.
* **Included credits** are the usage line's `includedQuantity`. They come with the deal at no charge.

Paid grants sold plus included credits on the credit benefit and bills only the sold credits. Both split evenly across the order's billing periods: an annual order grants and charges everything once, a monthly order grants and charges one twelfth each month. The overage rate applies once the granted credits run out.

Paid keeps a fractional overage price per credit exactly when sub-cent pricing is enabled for your organization. It multiplies that rate by the credits used and rounds the billed total once. For example, $0.004 per credit for 1,000 credits bills $4.00. A positive rate below one cent is accepted with the flag enabled; an explicit `0` means free overage. Fractional rates are refused when the flag is off.

New fractional rates are stored in `overageUnitPricesDecimal`, keyed by billing currency, as decimal strings in that currency’s stored units. Whole rates use the existing whole-number fields. The sync mapping view shows the exact rate. New orders do not write `overageUnitPriceExactCents` or `overageUnitPriceBilledCents` metadata.

Orders previously synced at a rounded-down rate retain that billed rate and their original exact-rate metadata. Repricing them is a separate fenced transition; it affects only invoices that have not yet been issued.

For example:

* **A sold bundle.** A 12-month order billed annually pre-commits 10,000 credits at a net rate of 13.5¢ (list 15¢). Paid grants 10,000 credits and bills $1,350.00 for them. With a 10-seat licence at $10.80 per seat per month, the platform price is $1,296.00 and the Paid order totals $2,646.00, the SalesBricks grand total.
* **An included allowance.** A 12-month order billed annually has 200 seats at $15.00 per month and a credits line with 27,000 included credits, no pre-commitment, and a 15¢ overage. Paid grants 27,000 credits on a $0.00 credits line, bills \$36,000.00 for the seats, and rates usage beyond the allowance at 15¢ per credit.
* **Both, billed monthly.** A 12-month order billed monthly pre-commits 12,000 credits at 13.5¢ and includes another 12,000. Paid grants 2,000 credits each month and bills \$135.00 per month for the 1,000 sold credits in each period.

### One-time fees

One-time fees come from the deal, not the Paid catalog. Paid sums the post-discount `grandTotal` of every one-time line on the order:

* If the total is more than zero, it bills once on the Paid product's one-time attribute.
* If the total is zero, or the order has no one-time lines, the product's one-time attributes are left off the order. A \$0 services line such as "Implementation & Support" provisions normally.

One-time lines are summed and placed by role, so their names and codes do not need to match anything in Paid.

### Contract rules

An order that breaks one of these rules is rejected, and the sync log shows which rule and which field:

* The buyer has an external id in SalesBricks, and none of the ids it lists belongs to another customer in Paid.
* The order carries exactly one usage brick, and its `code` equals the `externalId` of a product in Paid.
* The order is a `STANDARD` order on a monthly, quarterly, semi-annual, or annual billing schedule, with a term of at most 12 months that divides into whole billing periods.
* The usage line sets either a pre-commitment or a quantity, not both. Included credits can sit alongside either.
* Sold plus included credits divide evenly by the number of billing periods, and the sold credits' price per period is a whole number of cents.
* Usage and subscription lines are flat-rate and not ramped. A fractional overage rate needs sub-cent pricing enabled for your organization; see [Sold and included credits](#sold-and-included-credits).
* The order has at most one subscription line, and the Paid product has exactly one recurring attribute to carry its price.
* One-time fees above zero need exactly one one-time attribute on the Paid product.
* The order currency has price points on the Paid product's attributes.

Orders without a mapped usage brick are not usage deals. They are skipped and never provision, which keeps any legacy order book out of Paid by construction.

## Set up the deal product in Paid

Create one product in Paid that models the whole deal:

1. Set the product's `externalId` to the SalesBricks usage brick's `code`.
2. Add a recurring credits attribute with a credit benefit. The deal's credits land on this attribute: sold plus included credits as the grant, the sold credits' price as the attribute price, and the deal's overage rate on the benefit. The attribute's own price and benefit amount act as placeholders, since every deal overrides them.
3. Add one recurring attribute for the platform subscription. The deal's net rate replaces this attribute's catalog price on each order.
4. If your deals carry one-time fees, add one one-time attribute. The deal's one-time total replaces its catalog price, and the attribute is left off orders with no one-time fee.
5. Add the usage meter attribute with its event name and rate, so signals rate against the order.
6. Make sure every attribute has a price point in the currency your deals close in.

## Connect your SalesBricks account

Go to **Settings → Integrations** and find the SalesBricks card. Click **Connect**, paste your SalesBricks API key, and confirm.

Paid validates the key against SalesBricks and stores it securely. Syncing starts from the moment you connect: orders closed before connecting are not imported.

> **Note**
>
> If the SalesBricks API key is rotated, polling stops and the card shows a
> reconnect warning. Reconnect with the new key to resume. The sync picks up
> where it left off.

## Monitor the sync

Click **Manage** on the SalesBricks card to open the integration page. It shows the connection status and the sync log: every closed-won order the polling detected and what it did in Paid. Provisioned rows link to the created Paid order.

**Sync now** runs a poll immediately instead of waiting for the next cycle.

### Inspect the field mapping

Select any sync log row to see the field-level mapping for that order: which SalesBricks fields the sync read (usage brick code, sold and included credits, per-credit rate, overage rate, subscription net rate, one-time total, currency) and where each value lands in Paid (matched product, credits granted and bundle price, per-period platform price, one-time fee).

Rejected rows show the same view plus the reject reason, so you can see exactly which field caused the problem, and skipped rows show why nothing was provisioned. Fix it in SalesBricks or in Paid, then click **Retry** on the row: Paid reads the order from SalesBricks again, with its pricing, and re-processes it, so the fix takes effect wherever you made it. If SalesBricks no longer lists the order under its buyer, the retry uses the order as first detected, and the row's detail says so. If the order is no longer closed in SalesBricks (deleted, lost, or reopened), the retry is skipped and nothing is provisioned. New orders picked up by polling use the corrected setup automatically.

Two rejections retry themselves, because their fix is made on the buyer in SalesBricks and the poll can see it: an order rejected because its buyer had no external id, and an order rejected because one of the buyer's ids already belongs to another customer in Paid. Once the buyer's external ids change in SalesBricks (the id is set, or the conflicting id removed), the next poll replays the order without a click, and the sync log shows the replay as a new row with the reason it was replayed. A fix made in Paid, such as deleting the draft customer that holds the id, and every other rejection wait for **Retry**.

An order skipped because it had no usage brick is re-checked too, more slowly: adding the brick does not change the order in the poll's listing, so about once an hour, for 30 days after the order was detected, Paid re-reads the pricing of such orders and re-processes any that now carry a usage brick.

## What's not supported yet

* **Renewals, upgrades, and recasts.** Only `STANDARD` orders sync. Other order types are rejected and visible in the sync log.
* **Custom and all-upfront billing schedules.** Monthly, quarterly, semi-annual, and annual schedules are supported.
* **Multi-year terms.** Terms longer than 12 months are rejected.
* **Tiered and volume pricing on deal lines** and ramped pricing.
* **Multiple usage bricks on one order.**
* **Backfill.** Orders closed before connecting are not imported. Contact Paid support if you need historical orders imported.

## Troubleshooting

**An order was rejected with "buyer ... has no external id in SalesBricks".** The buyer company has no external id set. Set it in SalesBricks to the customer id your signals send for that customer. The next poll, within about a minute, replays the order on its own; **Retry** on the row does the same immediately.

**An order was rejected with "buyer ... external id ... already belongs to ...".** One of the ids in the buyer's external id is the external id, alias, or customer unit id of a different customer in Paid; the reason names that customer. Most often it is a draft customer that a signal created under that id before the deal closed. Remove the id from the buyer's external ids in SalesBricks, and the next poll replays the order on its own; or delete the draft customer in Paid if it holds nothing else, then retry the row from the sync log.

**A retry failed with "order ... belongs to the Paid customer with external id ...".** The order is already active in Paid on one customer, but the buyer's first external id now names a different one, so the buyer's further ids were not registered as aliases. Put the external id of the customer that owns the order first in the buyer's external ids in SalesBricks, then retry the row from the sync log.

**An order was rejected with "no Paid product with externalId ...".** The usage brick's `code` in SalesBricks does not match any product `externalId` in Paid. Set the brick code, or fix the product's `externalId`, then retry the row from the sync log.

**An order was rejected with "no ... price point".** The deal closed in a currency the Paid product has no price points for. Add price points in that currency to every attribute on the product, then retry.

**An order was rejected for its one-time fees.** The deal has a one-time total above zero, but the Paid product has no one-time attribute, or more than one. Give the product exactly one one-time attribute, then retry.

**An order was skipped with "no usage brick on the order".** None of the order's lines is a usage brick, so Paid treated it as a non-usage deal and provisioned nothing. If it is a usage deal, add the usage brick to the order in SalesBricks. A change to the order's bricks does not move the order's updated time, so polling cannot see it; instead, for 30 days after the order was detected, Paid re-reads the order's pricing about once an hour and re-processes the order on its own once a usage brick is there, as a new row in the sync log. **Retry** on the row does the same at once. Either way the buyer still needs an external id: an order re-processed without one lands as rejected, and is replayed once the id is set.

**An order I expected to sync never appears.** The sync only processes orders that reach the closed stage after you connect. Check the order's stage in SalesBricks.

**The card shows "Sync is failing".** The stored API key most likely stopped working, for example after a rotation in SalesBricks. Reconnect with a current key.

## Related

* [Credits](/documentation/credits/credits)
* [Examples of plans with included credits](/documentation/credits/examples-of-plans-with-included-credits)
* [Xero integration](/documentation/integrations/xero)