Subscriptions

Give a subscriber credit

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.

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)

Path parameters

idstring uuid required

Subscription UUID (the id field from the list response, not stripeSubscriptionId).

Headers

Idempotency-Keystring required

Required, not optional. Mint one string per credit you mean to give, and send the same one again if the call times out and you retry. Nothing on our side survives a retry to recognise it by, so a retry without a key credits the subscriber a second time. Two different keys for the same amount give two credits, which is how you deliberately credit someone twice.

Request body

amountMinorinteger 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.

reasonstring required

Why you gave it. Shown back to you and on the credit at the processor.

Response

The credit was given.

idstring required

The credit's id at the payment processor. There is no id of ours.

amountMinorinteger required

What you gave, positive.

currencystring required

The subscription's, lower-case.

reasonstring required
creditBalanceMinorinteger required

All unspent credit on this customer's account with you.

nextInvoiceMinorinteger required

What their next invoice would have taken before this credit.

nextInvoiceDueAfterCreditMinorinteger required

What it will take now.

nextInvoiceAtstring date-time required
createdBystring uuid required

The person who gave it.

createdAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.