How do we show customers a clear usage history before they dispute an AI bill?

Why Transparent Usage History Matters

Show the agreed billable unit, period and completed work behind each charge. This proposed design makes charges inspectable; it does not claim measured reductions in disputes or satisfaction. All dates, quantities and customer examples below are hypothetical. However, exposing detailed usage data must balance transparency with protecting provider secrets and other customers' privacy.

Key Elements to Display in Usage History

1. Billable Units: Show the agreed customer value unit, such as completed image tasks. Provider compute or API calls are billable only if the approved plan uses that unit.
2. Period Boundaries: Clearly mark the billing period start and end dates.
3. Completed-Task References: Provide identifiers or descriptions of AI tasks completed (e.g., job IDs) without exposing sensitive internal processing details.

This approach gives customers concrete evidence to verify charges.

Protecting Provider Secrets and Other Customers' Data

Never return another organisation’s usage to a customer. Hiding names or aggregating data does not replace authorisation. Provide stable customer-visible task references and a field allow-list excluding secrets and unnecessary provider diagnostics. Implement row-level security (RLS) in your database to ensure customers access only their own usage data, as described in Supabase row-level security.

Designing the Customer Portal Interface

Create a dedicated usage history section in the portal:

• Display a summary table with billing periods and total units.
• Allow customers to drill down into each period to see task references and usage details.
• Use pagination or filters to manage large data sets.

Refer to the user journey guide for structuring this flow.

Handling Disputes and Drilldown

Include a dispute initiation button next to each billing period or task entry. When customers dispute a charge:

• Provide a form to specify the issue.
• Show detailed usage evidence relevant to the disputed item.
• Log and track disputes for support follow-up.

This process improves transparency and resolution efficiency.

Integration with Usage-Based Billing Systems

If using Stripe for usage-based billing, leverage their usage recording APIs as a reconciliation input. Billing Meter events are processed asynchronously, so summaries and upcoming invoices may lag. Keep the reviewed product ledger authoritative for billable work and show pending synchronisation instead of converting missing data to zero. Verify Stripe's availability for South African entities as per Stripe country availability.

For recurring billing via Payfast, understand their subscription features and how to reconcile usage data with payments.

Technical Considerations

• Ensure your webhook handlers verify event signatures as per Stripe webhook guidance to maintain data integrity.
• Use secure file storage for usage reports, considering signed URLs and cache expiry.
• Implement API rate limiting and data caching to optimise portal performance.

Worked Example: AI Text Generation Service

For this separate hypothetical token-based plan, assume the customer agreed to billing per 1,000 eligible tokens with retry and rounding rules documented. This is not a current provider price or a default unit for every AI product.

• Billing period: 1–31 March 2027
• Customer usage: 150,000 tokens
• Portal shows:
  • Period: 01 Mar 2027 – 31 Mar 2027
  • Billable units: 150 (thousands of tokens)
  • Task references: List of job IDs with timestamps (e.g., job_20270301_001, job_20270315_023)

Customer can drill down to see how many tokens each job consumed without seeing raw input/output or provider internals.

Practical Output: Usage History Design Template

Use this template to build your customer-facing usage history API and UI.

If your business needs help designing clear usage histories or integrating usage-based billing, explore our pricing models and SaaS development services. For custom portal design, check CMS vs custom development and understand ongoing costs in website maintenance costs. Get in touch to discuss your specific needs.

Implement tenant-scoped access to usage history

Bind each query to the authenticated caller, active organisation and billing permission. An internal customer ID such as cust_12345 is not automatically a Supabase Auth user ID. A policy equating those identifiers would be wrong unless the schema deliberately makes them the same identity.

Use a verified membership relationship to authorise organisation records. Several billing members may legitimately share access, and one person may work for several organisations. The server must verify the selected organisation rather than trust a supplied customer ID.

Supabase’s RLS guide describes grants, policies and privileged bypass paths. RLS does not automatically hide secret columns. Administrative clients can bypass policies, so authorise backend routes and return an explicit allow-list of customer-visible fields.

Proposed access-test procedure

1. Create Alpha and Beta organisations with distinct usage markers.
2. Confirm Alpha’s billing member can read Alpha’s period and task records.
3. Request Beta’s known period or task identifier with Alpha’s token.
4. Confirm no Beta rows, totals, task names, report links or protected metadata escape.
5. Repeat for a non-billing member, an unauthenticated caller and exports.
6. Remove membership; test the existing token and refreshed session. Document any JWT-derived access delay.
7. Exercise the actual application endpoint, including privileged backend paths.

Record caller, organisation, request, expected decision and response-field inspection. Run a positive control so an outage cannot disguise a denial success. Keep tokens and raw prompts out of shared reports.

Keep charges and corrections inspectable

Use one stable product reference per billable outcome. Record plan version, quantity, unit, period and billing decision. A provider retry is not automatically another completed customer task.

Append reviewed corrections as adjustments linked to the original reference. Show original quantity, adjustment and revised total. Do not erase evidence or silently rewrite a finalised invoice. Any financial correction must follow its authorised provider workflow and be verified separately.

Tasks that have not reached the plan’s billable completion state should be pending or non-billable under the proposed rule. This may differ from provider token consumption. Agree the customer unit and retry treatment before presenting charges.

Designing a Dispute Resolution Workflow in the Customer Portal

A clear dispute process integrated into the usage history interface helps resolve billing questions efficiently.

Workflow Design:

1. Dispute Button:

   • Place a dispute initiation button next to each billing period summary and individual task entry.

2. Dispute Form:

   • Collect:
     • Dispute reason (e.g., incorrect usage, duplicate charge).
     • Reference to the specific billing period or task.
     • Optional comments or attachments.

3. Evidence Display:

   • Show relevant usage details alongside the form to help customers confirm their dispute.

4. Submission and Tracking:

   • Log submitted disputes in a support ticketing system.
   • Provide customers with a dispute reference number.
   • Display dispute status (Pending, Under Review, Resolved).

5. Support Team Integration:

   • Notify support staff automatically.
   • Allow staff to update dispute status and add resolution notes.

Acceptance Tests:

• Customer can open dispute form from usage history.
• Dispute form validates required fields.
• Submitted disputes appear in support backend.
• Dispute status updates are visible to the customer.

Failure Tests:

• Attempt to dispute without selecting a billing period or task should show an error.
• Unauthorized users cannot dispute other customers' usage.
• System handles simultaneous disputes on the same usage item gracefully.

Recovery Steps:

• If dispute submission fails, prompt customer to retry or contact support directly.
• Implement retry logic for backend logging failures.

Hypothetical Case Study: AI Image Processing SaaS Usage History

Scenario: A South African SaaS offers AI image processing billed per completed image task.

Customer: cust_7890

Billing Period: 1–31 May 2027

Usage Data:

Total Billable Units: 500 images

Customer Portal Display:

• Billing Period: 01 May 2027 – 31 May 2027
• Total Units: 500 images
• Task References:
  • imgproc_20270501 (100 images)
  • imgproc_20270515 (250 images)
  • imgproc_20270530 (150 images)

Dispute Example:

Customer disputes the 250 images processed on 15 May.

Dispute Form Details:

• Reason: "I did not submit images on 15 May."
• Task Reference: imgproc_20270515

Support Process:

• Support reviews logs confirming task submission time and image count.
• Verify the authorised submission, completed outcome, plan version and absence of duplicate billing before concluding the charge is supported.
• For an unsupported charge, record an approved adjustment and verify any required provider operation before marking the dispute resolved.

Acceptance Criteria for Usage History:

• Only authorised billing members of the organisation owning cust_7890 may see these records.
• Stable customer-visible references preserve traceability without exposing secrets or unrelated records.
• Billing period boundaries clear.
• Dispute button available per task.

Failure Handling:

• If task data is missing, show "Data unavailable" with contact support link.
• If dispute submission fails, notify customer and log error.

This case study illustrates practical application of transparent usage history and dispute handling while safeguarding data privacy and provider secrets.

Frequently asked questions

How detailed should the usage history be?

Show enough detail for customers to verify charges confidently, such as aggregated units and task references, but avoid exposing raw logs or provider secrets.

How do I ensure data privacy for other customers?

Implement row-level security and strict access controls so customers can only see their own usage data.

Can I use Stripe's tools for usage visibility?

Yes, Stripe's Metronome supports real-time usage tracking and billing, but check geographic availability for South Africa.

What if a customer disputes a charge?

Provide a clear dispute workflow in your portal with evidence display and support ticket integration.

Related guides

For further background, read our marketing dashboard metrics and attribution for lead generation. The analytics glossary explains the terminology used in those guides.

Sources

• Stripe usage-based billing
• Supabase row-level security
• Stripe webhook guidance
• Payfast subscriptions
• Stripe country and extended-network availability