Skip to navigation

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

SalesBricks fieldLands in Paid as
Buyer externalIdThe externalId of the Paid customer the order belongs to
Usage brick codeThe Paid product whose externalId matches
Usage line preCommitment (or quantity on older orders)Sold credits, granted and billed
Usage line includedQuantityIncluded credits, granted at no charge
Usage line netRatePer-credit price of the sold credits
Usage line overageUnitPriceOverage 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 × quantityPlatform price per billing period on the recurring attribute
One-time lines grandTotal, summedOne-time fee on the one-time attribute
Order billing schedule, start and end datesBilling frequency and term of the Paid order
Order currencyCurrency 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.004percreditfor1,000creditsbills0.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.00forthem.Witha10−seatlicenceat1,350.00 for them. With a 10-seat licence at 10.80 per seat per month, the platform price is 1,296.00andthePaidordertotals1,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.00permonthandacreditslinewith27,000includedcredits,nopre−commitment,anda15¢overage.Paidgrants27,000creditsona15.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.
  • 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.

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.