---
title: "Give a subscriber credit"
method: POST
path: "/gateway/subscriptions/{id}/credits"
tags: ["Subscriptions"]
---

# Give a subscriber credit

`POST /gateway/subscriptions/{id}/credits`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits`
- Auth: `SessionAuth` (a scheme the document does not define)

Puts credit on the subscriber's account with you. It comes off their next invoice, reducing what their card is charged; no money moves out, and no receipt already issued changes. The credit belongs to the CUSTOMER, so if the same buyer has two subscriptions with you in the same currency it goes to whichever invoice falls due first. The amount is positive integer minor units and may cover the whole of the next invoice — at most its amount due. A credit that covers it in full charges the card nothing, and that month is still recorded as a sale of zero with an invoice and a receipt saying the credit covered it. More than the amount due is refused, and the error names the largest amount you can give. The currency is the subscription's; there is no currency field. Only an owner or admin may do this, from a signed-in session: an API key cannot, because the credit must name the person who gave it.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string, required

## Request body

- GrantCreditRequest
  - `amountMinor` integer, required: Positive integer minor units of the subscription's currency, at most the next invoice's amount due. There is no currency field: a credit in the wrong currency is accepted by the processor and then never reaches an invoice.
  - `reason` string, required: Why you gave it. Shown back to you and on the credit at the processor.

## Response `201`

The credit was given.

- SubscriptionCredit: A credit you gave, with both figures it changes. Money is integer minor units.
  - `id` string, required: The credit's id at the payment processor. There is no id of ours.
  - `amountMinor` integer, required: What you gave, positive.
  - `currency` string, required: The subscription's, lower-case.
  - `reason` string, required
  - `creditBalanceMinor` integer, required: All unspent credit on this customer's account with you.
  - `nextInvoiceMinor` integer, required: What their next invoice would have taken before this credit.
  - `nextInvoiceDueAfterCreditMinor` integer, required: What it will take now.
  - `nextInvoiceAt` string, date-time, required
  - `createdBy` string, uuid, required: The person who gave it.
  - `createdAt` string, date-time, required

## Other responses

- `400`: A required field is missing, out of range, or the wrong type. `ValidationPipe` also rejects any field not in the documented schema.
- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.
- `404`: Resource not found (or not visible to your key; the two are not distinguished).

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)