Real Examples

A developer on the Free plan ($0, 10,000 adds / 1,000 retrievals) needs more capacity and upgrades to Starter ($29/mo, 50,000 adds / 5,000 retrievals).

1. The developer clicks “Upgrade” in the dashboard and completes payment checkout.
2. A successful payment is recorded against the organization. The event is deduplicated, so even if it is delivered more than once, the upgrade is applied only once.
3. Counters reset to zero — even if the developer had used 8,000 of 10,000 adds on Free.
4. Plan changes to Starter immediately, and the organization’s tier is updated at the same time.
5. A new billing cycle starts anchored at the payment timestamp (e.g., May 9 → June 9).
6. The account is marked active. Any previous failure flags are cleared.
7. A branded payment receipt email is sent to the billing contact with a PDF invoice attached.

A team on Pro ($179/mo, 250,000 adds) decides to downgrade to Starter ($29/mo, 50,000 adds) on May 15, with their cycle ending June 9.

1. An admin clicks “Downgrade” in billing settings. Starter is scheduled for the next cycle.
2. Nothing else changes. The plan stays Pro, limits stay at 250,000 adds and 25,000 retrievals, and the cycle window stays May 9 → June 9.
3. Between May 15 and June 9, the team continues using Pro limits. They have already paid for this period.
4. On June 9, the cycle rolls over and the scheduled downgrade is applied:
5. Counters reset to zero.
6. Plan changes from Pro to Starter.
7. The downgrade schedule is cleared.
8. A new cycle starts: June 9 → July 9 with Starter limits (50,000 adds / 5,000 retrievals).

An organization on the Free plan (10,000 adds/month) has used 9,999 add requests. The 10,000th request arrives, followed by the 10,001st.

1. Request 10,000: The atomic check finds usage at 9,999, admits the request, and advances the counter to 10,000. The memory is processed normally — stored, embedded, and indexed.
2. Request 10,001: The atomic check sees usage already at the limit (10,000) and refuses to admit it. The counter does not advance.
3. The API returns 200 OK. No memory is stored, embedded, or indexed — the write pipeline is skipped entirely. Your application sees no error.
4. The dashboard now shows the add-requests metric at 100% of its plan limit, and any usage alerts you have configured fire.
5. All subsequent add requests are silently degraded until the cycle resets or the organization upgrades.

A Pro plan customer’s card expires. When the subscription renewal is attempted, the payment fails.

1. The payment is identified as an autopay failure (subscription renewal), not a one-off payment failure.
2. Immediate downgrade to Free. The plan changes from Pro to Free and the organization’s tier is updated at the same time.
3. Usage counters reset to zero. A new cycle window starts anchored at the failure timestamp.
4. The account is marked past-due so the dashboard can surface a clear payment-action banner.
5. The paid subscription itself is intentionally preserved — this allows a later retry to automatically restore the plan.
6. Any pending scheduled downgrades or cancellations are cleared (an autopay failure invalidates them).

Following the autopay failure above, the payment is retried 3 days later and succeeds.

1. The successful payment is detected. The org is currently on Free with a past-due marker, so this is treated as a recovery after failure.
2. Counters reset to zero (again — they may have accumulated some Free-tier usage during the 3-day gap).
3. The plan restores to Pro. The plan associated with the payment is applied.
4. The cycle window syncs to the payment’s period (if provided), or a fresh cycle starts at the payment timestamp.
5. All failure flags are cleared and the account is marked active.

From the customer’s perspective, they were on Free for 3 days and are now back on Pro with fresh limits.

A Scale plan customer wants to cancel. Their cycle runs May 9 → June 9.

1. The customer clicks “Cancel subscription” on May 20. The cancellation is scheduled for the end of the current cycle.
2. Nothing else changes. Scale limits remain in effect and the cycle stays May 9 → June 9.
3. On May 25, the customer changes their mind and clicks “Resume”. The cancellation is reversed and no transition happens at rollover.
4. Alternatively, if they do not resume, on June 9 the rollover runs:
5. Counters reset to zero.
6. The plan reverts to Free.
7. The paid subscription is cleared.
8. Any scheduled plan changes are dropped (cancellation supersedes everything).
9. A new cycle starts: June 9 → July 9 with Free limits (10,000 adds / 1,000 retrievals).

An organization has an active Pro plan with a Starter downgrade scheduled. Their cycle ends on June 9.

1. On June 9, the first API request after midnight UTC triggers the rollover check. The rollover is concurrency-safe — only one rollover ever runs even if multiple requests arrive at the boundary.
2. Step 1: Reset counters. Both usage counters and the cycle’s spend total are reset to zero. The old cycle’s usage is gone.
3. Step 2: Apply the scheduled plan. No cancellation is pending, so the scheduled Starter downgrade is applied. The plan changes to Starter, the organization’s tier is updated, and the downgrade schedule is cleared.
4. Step 3: Advance the window. The new cycle window is June 9 → July 9 (the next calendar-month anniversary).
5. Subsequent requests in the new cycle use Starter limits (50,000 adds / 5,000 retrievals).