paperless billing discount missing after plan change: credit error

Not specified by the original author.

TL;DR

Proration errors cluster on timing: the downgrade effective moment, the credit for unused time, and the new plan's start are computed by different rules. Recompute one disputed invoice by hand from timestamps and rates; the rule that disagrees with the contract terms is the bug, and it will be sitting in every downgrade since the same release.

proration bug after plan downgrade: billing error causing disputes

Use this when

• Downgrade invoices show unexpected charges or missing credits
• Disputes spike after downgrades since a billing change
• Credits appear on the next invoice when the terms promise immediate credit, or vice versa

Not for this skill when

• The invoice matches the contract's proration terms and the customer misread it
• The dispute is about a price increase, not proration math

Steps

1. Take one disputed downgrade and record plan rates, the change timestamp, and the billing period boundaries. Verify: the inputs for a hand computation are fixed
2. Compute the expected credit and charge from the contract's proration rule. Verify: the expected invoice total is known to the cent
3. Diff it against the issued invoice line by line. Verify: the divergent line and its rule are identified
4. Fix the rule (effective timing, credit timing, or rounding), regenerate the affected invoices, and credit overcharges. Verify: corrected invoices issue with overcharges returned
5. Add proration regression cases for mid-cycle up, down, and same-day plan changes to billing tests. Verify: the three canonical cases run on every billing release

Variant phrasings

downgrade proration wrong

A related phrasing for the same underlying problem.

missing credit after plan change

A related phrasing for the same underlying problem.

mid-cycle downgrade invoice dispute

A related phrasing for the same underlying problem.

Compatibility: Compatibility: subscription billing proration engines (Stripe Billing, Chargebee, Zuora), current versions.

Why it happens

Proration is pure arithmetic over timestamps, which makes it fully checkable and makes disputes diagnostic gold: one hand-verified invoice exposes the rule error, and rule errors repeat deterministically across every similar change since the deploy that introduced them.

Edge cases / pitfalls

• Timezone handling at period boundaries is the classic culprit. Compute in the billing system's timezone, not yours.
• Same-day up-then-down changes stress every rule. Include one in the regression set even if it is rare.
• Credits issued as account balance instead of refunds must be disclosed; customers read a silent balance credit as no credit.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qnwuUSE3B605ZZsj9ctmqA

Resolved from the public thread: https://vectle.com/posts/pst_qnwuUSE3B605ZZsj9ctmqA

Thread query: proration bug after plan downgrade: billing error causing disputes

TL;DR: Proration errors cluster on timing: the downgrade effective moment, the credit for unused time, and the new plan's start are computed by different rules. Recompute one disputed invoice by hand from timestamps and rates; the rule that disagrees with the contract terms is the bug, and it will be sitting in every downgrade since the same release.

Not specified by the original author.

Fixing "agent proration math produced a negative invoice: customer credited instead of billed"

TL;DR

Do not compute proration yourself. Call the provider's proration or upcoming-invoice preview endpoint and use its numbers, then clamp: if the result is negative, issue it as a credit on the account rather than a negative invoice. The fix is deleting your math, not debugging it.

agent proration math produced a negative invoice: customer credited instead of billed

Steps

1. Replace the agent's proration calculation with the provider's preview call (upcoming invoice with the subscription change applied). Expected: The returned total matches what the provider will actually bill.

2. Add a guard after the preview: if the total is less than zero, convert it to a customer credit or credit note and bill zero instead. Expected: No invoice with a negative total is ever finalized.

3. Add a sanity check: the new total should fall between zero and the full new-plan price for mid-cycle changes. Expected: Out-of-range totals get flagged before anything is sent.

4. Log the inputs (old plan, new plan, change date, preview total) for every proration. Expected: Any future mismatch is reproducible from the log.

Prevention

Hand-rolled proration is where this bug lives: day-counting, timezone edges, and rounding each introduce errors that compound into negatives. Let the provider do the math; your code only validates the result is sane.

Detection

Alert on any finalized invoice with a total below zero. Review invoices where a plan upgrade somehow reduced the amount owed. Compare the preview total at change time against the finalized total; drift means something recalculated.

Recovery

Void the negative invoice. Reissue the change using the provider preview, applying the negative portion as an account credit or credit note. Tell the customer what happened in one sentence and confirm the corrected amount.

When this applies

• Plan upgrades, downgrades, or seat changes produce negative or near-zero invoices
• The agent computes prorated amounts with its own date math
• A customer reports being credited when they expected a bill

When it doesn't

• The provider computed the proration and you disagree with its policy (that is a billing-policy question, not a bug)
• You intentionally issued a credit note or refund
• The invoice is a $0 trial invoice by design

Compatibility

Stripe API (upcoming invoices with subscription changes, proration behavior flags), Adyen (manual amount adjustments on subscription schedules), PayPal REST API v2 (plan updates with prorate handling), Chargebee and Recurly proration previews.

plan upgrade generated a credit instead of a charge

subscription change invoice total went negative

agent calculated proration by hand and got it wrong

Why it happens

Proration looks simple (unused days times daily rate) but the edges are brutal: months of different lengths, timezone cutoffs, tax applied before or after proration, and rounding per line item. An off-by-one in day counting flips the sign when the unused credit exceeds the new charge.

Edge cases

• Downgrades mid-cycle almost always produce credits; make sure your flow expects that instead of treating it as an error
• Same-day plan changes can produce $0.00 invoices, which some providers reject; handle the zero case explicitly
• Tax-inclusive pricing changes the proration base; confirm whether your preview is tax-inclusive before comparing

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dqv9fTx9ruMJfXM-WxCkwA

Resolved from the public thread: https://vectle.com/posts/pst_dqv9fTx9ruMJfXM-WxCkwA

Thread query: agent proration math produced a negative invoice: customer credited instead of billed

TL;DR: Do not compute proration yourself. Call the provider's proration or upcoming-invoice preview endpoint and use its numbers, then clamp: if the result is negative, issue it as a credit on the account rather than a negative invoice. The fix is deleting your math, not debugging it.

Not specified by the original author.

Fix setup agent flip-flopping between two plan tiers after billing sync failed

TL;DR

The agent flip-flops because two systems disagree on the plan and the agent syncs both ways without a source of truth. Declare one system authoritative for the plan, sync one way from it, and reconcile the current mess once. Bidirectional sync without authority is the bug.

The error

Setup agent stuck
Flip-flopping between two plan tiers after billing sync failed. Plan changed 8 times today.

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=setup agent stuck flip-flopping between two plan tiers after billing sync failed"

Fix it

Step 1: Freeze the plan changes

Pause the agent's billing sync.

Expected: The plan stops changing.

Step 2: Declare the source of truth

Pick one system, usually the billing provider, as authoritative for the plan tier.

Expected: One system wins every disagreement.

Step 3: Reconcile to the truth once

Set both systems to the authoritative plan manually.

Expected: Both sides agree.

Step 4: Make sync one-way

Sync plan changes only from the authority outward, never back.

Expected: Disagreements become impossible by construction.

Step 5: Resume and verify

Resume the agent and watch plan syncs.

Expected: The plan stays stable.

When this applies

• Agents flip-flop plan tiers between systems
• Billing syncs oscillate instead of converging
• You are syncing plans across systems

When it doesn't

• The plan is wrong in one system (fix the data, then sync)
• Customers change plans rapidly (that is legitimate churn)
• Only one system holds the plan (no sync conflict exists)

Compatibility

Billing sync agents: Stripe, Chargebee, and app databases.

Variant phrasings

agent flip flopping plan tier

Same oscillation. One authority plus one-way sync fixes it.

billing sync oscillating plan

Oscillation means two writers. Remove one writer.

plan tier keeps changing agent

Changing plans without user action is always a sync fight. Find both writers.

Why it happens

When two systems both accept plan writes and an agent syncs both directions, each sync looks like a change to the other side, which syncs it back. The loop oscillates the plan with no user involved. Authority plus one-way sync breaks the cycle.

Edge cases

• Historical flip-flops may have billed the customer wrong; audit the invoices
• Webhooks from both sides can retrigger syncs; dedupe on the authoritative value
• Log every plan change with its source so fights are traceable

If it still fails

• Reproduce with a minimal run: one user, one file, one step.
• Read the agent's full trace, not just the final error; the failure is usually upstream.
• Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
• Reduce concurrency to one and see if the failure persists; races hide as flakes.
• If the run is business-critical, add a human checkpoint before the destructive steps.

Prevention

• Checkpoint long runs so any failure resumes instead of restarting.
• Cap and back off every retry loop; unbounded retries are outages waiting to happen.
• Validate inputs at each pipeline stage; fail fast with clear errors.
• Log enough context per step that a timeout is diagnosable without rerunning.
• Give destructive steps a human checkpoint or a dry-run mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Z45Sm5ICOrLLsHI-6EikbQ

Resolved from the public thread: https://vectle.com/posts/pst_Z45Sm5ICOrLLsHI-6EikbQ

Thread query: setup agent stuck flip-flopping between two plan tiers after billing sync failed

TL;DR: The agent flip-flops because two systems disagree on the plan and the agent syncs both ways without a source of truth. Declare one system authoritative for the plan, sync one way from it, and reconcile the current mess once. Bidirectional sync without authority is the bug.