---
title: "Billing History"
method: POST
path: "/margot/actions/billing_history"
tags: ["margot"]
---

# Billing History

`POST /margot/actions/billing_history`

## Request

- Base URL: `https://api.nanocorp.so` (the document declares no server; this is the origin it was published from)
- URL: `https://api.nanocorp.so/margot/actions/billing_history`
- Auth: HTTP bearer

Every charge NanoCorp made or tried on the caller's card, newest first (ungated read).

Plan invoices with their retry state, top-ups and domains
(:mod:`use_cases.support.billing_history`). Stripe is best-effort, flagged by
``invoices_available``.

## Request body

- MargotActionRequest: Common request body for every Margot action. Identity comes from the request: on a customer ticket Parahelp's tool fills it from the ticket's requester (never from the message text), on a team call the teammate names the founder. The backend resolves `external_id` (our `user.id`) or a unique `email` to the account server-side; it never trusts a company/conglomerate id from the body.
  - `external_id` string, nullable: The founder's NanoCorp user id (external_id on the helpdesk contact).
  - `email` string, nullable: The founder's email. Used as a fallback identity and a cross-check.
  - `company` string, nullable: Optional company name/handle hint, resolved against the caller's own companies.
  - `limit` integer, nullable: Optional row limit for list actions.

## Response `200`

Successful Response

- BillingHistoryResponse: Every way NanoCorp charges a founder, newest first: plan invoices, top-ups and domains. It does not say whether a payment was refunded later: ``account_summary``'s ``refundable_charges`` covers the last 35 days.
  - `found` boolean
  - `subscription_status` string, nullable
  - `entries` BillingHistoryEntry[]
    - `date` string, required: YYYY-MM-DD (UTC): when it was paid, or billed when unpaid.
    - `kind` string, required: plan, topup, auto_topup, domain or other.
    - `description` string, required: What it was for, e.g. 'Founder plan renewal', 'Plan change (prorated)', '50 credits'.
    - `amount` string, required: The invoice or payment total with currency code, e.g. '60.00 USD'. Negative for a plan change that left credit on the account, which later invoices use before the card.
    - `amount_paid` string, nullable: On a paid invoice, what was actually paid. Lower than amount when account credit covered part of it, and 0 when the credit covered all of it.
    - `status` string, required: paid; unpaid (billed and not paid yet: next_attempt_on says when the card is tried again, null when no retry is scheduled); uncollectible (retries ended unpaid); void (cancelled, nothing is owed); registration_failed (a domain paid for but not registered).
    - `amount_due` string, nullable: Still owed on an unpaid invoice.
    - `payment_attempts` integer, nullable: Card attempts so far on an unpaid invoice.
    - `next_attempt_on` string, nullable: YYYY-MM-DD of the next automatic card attempt. Null when none is scheduled.
    - `discount` string, nullable: Amount taken off by a coupon or promotion code.
    - `credits_granted` number, nullable: Credits this payment added, when known.
    - `hosted_invoice_url` string, nullable: The founder's own invoice page (view, pay, download). Null for a domain.
  - `invoices_available` boolean: False when the invoices could not be read: entries then hold only the top-ups and domains, so never conclude that a plan charge does not exist.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-06** `05989a402d6e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nanocorp/apis/nanocorp-api/changes/margot/actions/billing_history/post.md)

---

[API](https://skmtc.dev/nanocorp/apis/nanocorp-api.md) - [All operations](https://skmtc.dev/nanocorp/apis/nanocorp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nanocorp/apis/nanocorp-api/revisions/291bb76b720b?raw)