SalesBricks Integration

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

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.

Each buyer carries one customer id. An external id that lists several ids, separated by commas or spaces, matches none of your signals, so the order is rejected until the buyer’s external id holds a single id.

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.

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 exactly one external id in SalesBricks.
• 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. The overage rate is a whole number of cents.
• 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.

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

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, then retry the row from the sync log.

An order was rejected with “buyer … has multiple external ids”. The buyer’s external id lists more than one customer id. Paid supports one customer id per buyer: set the external id in SalesBricks to the single customer id your signals send, 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 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
• Examples of plans with included credits
• Xero integration