Documentation

Asaas has no product catalog

Asaas has no product catalog: a charge carries a free-text "description" field, typed in at issue time, and there is no product or price object for a subscription to point at. Two customers on the same plan can arrive with different descriptions, and nothing in the data says they are the same plan. That is why product segmentation is unavailable across the whole account while an Asaas source exists, and not only for the subscriptions that came from it: a filter that answered for half of your account and ignored the other half would look complete without being complete, and that is worse than no filter at all. Your MRR, your churn and your revenue do not change because of this; what disappears from Metrics is the product breakdown. There is no assumption to declare here: the data does not exist on the other side, and no amount of careful reading invents it.

Asaas records trials in no field at all

An Asaas subscription has not a single trial field: there is no "trialDays", no "trialEndDate", no equivalent, and sending any of them when creating a subscription is accepted with HTTP 200 and silently ignored (measured in the sandbox account). This is not a gap we can read our way around: to Asaas, giving 7 free days and issuing the first charge 7 days from now are the same operation, and that is how its own documentation tells you to run a trial. Not even Asaas can say who was on a trial. Consequence: in the Sales funnel, Trials Started sits at zero for this source, and Trial Conversion has nothing to measure. Your MRR does not change, because a subscription with no confirmed charge is already worth zero in our calculation: what is lost is the label, not the money. If you really do give a free period before the first charge, it only starts to exist once you declare the assumption in Settings, under Calculation Premises.

A free plan cannot be represented in Asaas

Asaas refuses any charge below R$ 5.00, and we measured it across the four payment methods: a value of zero returns 400 (to Asaas, zero reads as missing), one cent returns 400 ("the minimum value is R$ 5.00"), and R$ 100 with a 100% discount is refused too. This is not a limit of our reading: a user on your free plan has neither a subscription nor a charge in Asaas, they exist only in your own database. Consequence: in the Sales funnel, Freemiums Started sits at zero, Freemium Conversion has nothing to measure, and your free base does not show up in the Subscribers count. Your MRR does not change, because a free user brings no recurring revenue, but the top of your funnel looks smaller than it is in real life. No assumption fixes this: there is nothing to read, and we do not invent what was never recorded. If you need to measure your freemium, it would have to be declared through another source: the Custom data source accepts zero-value subscriptions.

Asaas has no event history

There is nothing in Asaas equivalent to Stripe's event history: you cannot list what happened, see the pending queue, or ask for a delivery to be sent again. If an event is lost, there is no one to ask what we missed. Consequence: the fact it carried, a payment or a cancellation, would stay out of your metrics, and nothing on the screen would give it away, because there is no second list to disagree with the first. Since we cannot ask, we raise alarms: the Data Sources screen tells you when the webhook was deleted or disabled, when Asaas paused the delivery queue after repeated failures (it holds paused events for 14 days, so resuming inside that window loses nothing; past it, they are gone for good), and when an event arrived and we failed to store it. Of those warnings, only the last one does not clear itself: the others leave the screen once the source is healthy again. A lost event does not come back, so when something was lost, the cure is to re-import the source, which reads your Asaas account again and rebuilds your history from what it answers. There is nothing to configure and nothing to declare: what we ask of you is to act on the warning when it shows up.

Asaas does not tell us when a customer changes

Asaas has no customer webhook: the four "CUSTOMER_*" events are refused with HTTP 400 when the webhook is created, while 24 others are accepted (we measured them one by one). A NEW customer still rides along with them, because the event for their subscription or their charge sends us to fetch them. What never reaches us is a CHANGE to someone already here: fixing a name, an email or a tax id in Asaas raises no event at all, and the new data only appears when you re-import the source. No metric changes because of this: MRR, churn and the Subscribers count do not depend on anyone's name, and what goes stale is the label you read under Customers. Re-checking every customer on every charge would fix it, and we do not do it: it would spend your account's API quota to correct data that moves no number. There is nothing to declare.

Trials only exist if you declare them

Since Asaas cannot tell "seven free days" apart from "first charge seven days from now", trials only exist if you DECLARE that your business has them, in Settings, under Calculation Premises. Without that, no customer is counted as a trial: it would be a guess, and a guess becomes a number on your screen. Once declared, the gap between the subscription being created and its first charge is read as a trial period, and the duration comes from the data itself, not from a number you type (which is why the question is yes or no, and not "how many days"). The side effect is stated plainly: if you also postpone the first charge for other reasons, a negotiation or a one-off deal, those subscriptions come in as trials and your trial metrics overstate. The assumption is off by default, moves only the Sales funnel and never the MRR, and turning it on or off recalculates your history right away.

Churn is dated at the end of the last paid period

A deleted Asaas subscription does not say when it was deleted: you get "dateCreated" and "nextDueDate", there is no "deletedDate", "canceledDate" or "endDate", and there is no event history to fish the date out of. Stamping the moment our sweep noticed the subscription was gone would be worse than having no date: the day of your churn would depend on when our robot ran, and reprocessing your history would move yesterday's chart. So we changed the question: "when did they cancel?" Asaas cannot answer, but "how far had they paid?" is recorded on every settled charge, and it stays there forever. The MRR span of an Asaas subscription is the union of its paid periods, and churn is dated at the end of the last one. In practice: someone who had paid through March 10 and did not renew shows up as churn on March 10, not on the day you deleted the subscription in the dashboard, so Customer Churn and MRR Churn follow the date in the data, not the date of your click. There is nothing to declare: this is the most faithful reading the Asaas data allows.

The biweekly cycle (BIWEEKLY) is treated as 14 days

Asaas has a cycle named "BIWEEKLY" and its documentation only calls it "quinzenal", an ambiguous word: in Portuguese it usually means 15 days (24 charges a year), in English biweekly means 14 (26 a year). We measured it by creating a real subscription in the sandbox account: the charges came out on July 14, July 28 and August 11, that is, 14 days. So the MRR of a biweekly subscription is its amount times 26, divided by 12. Guessing 15 days would take about 8% off the MRR of every subscription on that cycle, and the error would show up nowhere. If you do not use the biweekly cycle, this assumption touches none of your numbers, and there is nothing to declare.

A deleted customer is recovered through their charges

A deleted customer disappears from Asaas listings: "/v3/customers" has no "includeDeleted", so not even a full sweep of your base finds them. But they still answer by id (a direct GET returns HTTP 200), and their subscriptions and charges keep referencing that id. That is exactly what we use: when a subscription or a charge points at a customer the listing did not bring, we fetch that customer by id and bring them back. Without this recovery your history would lose people: in the real Asaas account we measured, 124 customers, 28% of the historical base, exist only because of it. Consequence: the Subscribers count, Customer Churn, ARPA and LTV also account for the people you have already deleted from Asaas, which is the right thing for a history, because their past did happen. There is nothing to declare.

Asaas has no read-only key

Every Asaas API key is full access, and there is no way to ask for less: the API specification has no "scope", no "permission" and no "readOnly", and the key creation body accepts only "name" and "expirationDate". This differs from Stripe, where we ask for a restricted key that, by construction, cannot move money: the key you paste here can issue charges, transfer money out of the account and delete customers. What we do with it is read, plus a single write: registering our own webhook. The HTTP client handed to the import, the drain and the sweep only knows how to GET, and the path that writes is locked to the "/webhooks" resource by a guard that a test keeps in place. Even so the risk is yours, and you have the right to know before pasting: you can revoke the key whenever you want in the Asaas dashboard, or create it with an expiry date up front (when it expires, syncing stops and the Data Sources screen tells you). None of this changes a number of yours: it is risk, not metric.

The Asaas API quota is yours, not ours

Asaas allows 25,000 requests every 12 hours per ACCOUNT, and that quota is shared with your own use of it: your site, your ERP and your checkout spend from the same pocket as our reading. If our sweep were the call that exhausted the quota, YOUR operation's calls would start failing, and that is unacceptable: a wrong metric is bad, freezing your cash flow is not negotiable. So every pass has a declared ceiling of 2,000 calls, about 8% of the 12-hour quota, and uses 6 concurrent calls even though Asaas accepts 50; when the ceiling is reached the sweep stops, says it stopped, and continues on the next pass, losing nothing. And we stop at the first rate-limit refusal, without insisting: Asaas returns no rate-limit header at all (we looked across some 55 requests and not one came back), so we cannot tell a burst limit apart from your quota running out, and in doubt your operation comes first. When that happens, the Data Sources screen raises the alarm. There is nothing to declare and nothing to configure.

In this source, you are the one reporting the data

In the other sources there is a gateway on the other side, and what it recorded is the reference everything is checked against. Here there is none: the subscriptions, the customers and the payments of this source are exactly the ones you declared, through the screen, a spreadsheet or the API. Consequence: what you declare is the truth, and every number in this account is computed from it. A subscription you forgot to declare shows up nowhere, and nothing gives it away, because there is no second copy to disagree with the first. For the same reason, this source holds the ONLY copy of this data: there is nowhere to re-import it from, removing the source erases what you declared and rebuilds your metrics without it, and that is why the screen asks for a backup first. There is no assumption to declare here: it is the nature of the source, and it is the same for someone declaring three subscriptions and for someone declaring three thousand.

The spreadsheet assumes one single amount per subscription

A spreadsheet row carries ONE amount; a subscription carries a HISTORY of amounts. There is no column that says "it cost R$ 99 until March and R$ 149 after that", so a spreadsheet can only claim one thing: this subscription was always worth this. That is what we assume when you upload the file, and the amount in the "amount" column applies from the subscription's start date onward. Consequence: if the price changed along the way, past months' MRR comes out at today's price, and the upgrade disappears from the month it happened in (in Metrics there will be no expansion or contraction there, and the chart rises as if it had always been that way). Uploading the spreadsheet again with the new price does not silently fix it: the whole upload is refused, because rewriting an amount you already declared changes the MRR of months that have closed, and that is an erratum, which you have to confirm. What to do: declare the subscription's price bands, on the screen or through the API, one band per price with the date it came into effect, and then each month uses that month's price and the upgrade shows up as expansion on the day it happened.