---
title: "Refund"
method: POST
path: "/margot/actions/refund"
tags: ["margot"]
---

# Refund

`POST /margot/actions/refund`

## 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/refund`
- Auth: HTTP bearer

Refund one of the founder's own payments (a plan charge or a top-up) in full.

Named by ``kind`` + ``charged_on`` from ``account_summary.refundable_charges``;
every rule is checked again here. A plan refund ends the plan now and takes
back the unused credits of that payment.

## Request body

- MargotRefundRequest
  - `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.
  - `requested_by` 'customer' | 'team', required: 'customer': the Customer Agent acting on a founder's ticket. 'team': the Internal Agent acting for a teammate.
  - `ticket_id` string, required: The helpdesk ticket id (customer) or the Parahelp task id (team). A repeated call with the same ticket_id returns the first result instead of acting twice.
  - `ticket_url` string, nullable: https link to the ticket or task, for the audit line.
  - `team_member` string, nullable: The teammate's email. Required when requested_by is 'team'.
  - `kind` 'plan' | 'topup', required: 'plan' or 'topup', as in refundable_charges.
  - `charged_on` string, required: YYYY-MM-DD (UTC), copied from refundable_charges.
  - `amount` string, required: What was paid, copied from refundable_charges as is, e.g. '15.00 USD': the refund runs only on the payment of that amount, the one the approval showed.
  - `note` string, nullable: Internal note, never shown to the founder. Kept to its first 500 characters.

## Response `200`

Successful Response

- MargotRefundResponse
  - `found` boolean
  - `outcome` 'done' | 'already_done' | 'pending' | 'refused', required: done: it happened now. already_done: an earlier call of this ticket already did it. pending: the refund went to the bank and its result is unknown, a teammate checks it. refused: nothing happened.
  - `reason` string, nullable: The refusal or pending code. Null when done.
  - `handoff` boolean: True: hand the ticket to a human now.
  - `kind` string, nullable: 'plan' or 'topup', as in refundable_charges.
  - `charged_on` string, nullable
  - `amount` string, nullable: Refunded, always the full payment, e.g. '30.00 USD'.
  - `credits_removed` number, nullable: Unused credits of that payment taken off the balance.
  - `credit_balance` number, nullable
  - `plan_ended` boolean: A plan refund ended the plan now.
  - `plan_cancel_pending` boolean: The money is refunded but the plan could not be ended; a teammate ends it.
  - `auto_topup_disabled` boolean: The refund turned auto top-up off.

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-26** `8a8592d6845d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nanocorp/apis/nanocorp-api/changes/margot/actions/refund/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)