Give a subscriber credit

curl --request POST \
  --url https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amountMinor": 500,
  "reason": "Two days of downtime in August"
}
'

import requests

url = "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits"

payload = {
    "amountMinor": 500,
    "reason": "Two days of downtime in August"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({amountMinor: 500, reason: 'Two days of downtime in August'})
};

fetch('https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountMinor' => 500,
    'reason' => 'Two days of downtime in August'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits"

	payload := strings.NewReader("{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "cbtxn_1NXyZ2eZvKYlo2C0",
  "amountMinor": 500,
  "currency": "eur",
  "reason": "Two days of downtime in August",
  "creditBalanceMinor": 500,
  "nextInvoiceMinor": 1900,
  "nextInvoiceDueAfterCreditMinor": 1400,
  "nextInvoiceAt": "2026-10-01T00:00:00.000Z",
  "createdBy": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "createdAt": "2026-09-14T10:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "amount is required when creating a session without a link",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 401,
  "message": "Invalid API key",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 403,
  "message": "Payment link belongs to another organization",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 404,
  "message": "Payment link not found",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

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

Give a subscriber credit

curl --request POST \
  --url https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amountMinor": 500,
  "reason": "Two days of downtime in August"
}
'

import requests

url = "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits"

payload = {
    "amountMinor": 500,
    "reason": "Two days of downtime in August"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({amountMinor: 500, reason: 'Two days of downtime in August'})
};

fetch('https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountMinor' => 500,
    'reason' => 'Two days of downtime in August'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits"

	payload := strings.NewReader("{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/credits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountMinor\": 500,\n  \"reason\": \"Two days of downtime in August\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "cbtxn_1NXyZ2eZvKYlo2C0",
  "amountMinor": 500,
  "currency": "eur",
  "reason": "Two days of downtime in August",
  "creditBalanceMinor": 500,
  "nextInvoiceMinor": 1900,
  "nextInvoiceDueAfterCreditMinor": 1400,
  "nextInvoiceAt": "2026-10-01T00:00:00.000Z",
  "createdBy": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "createdAt": "2026-09-14T10:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "amount is required when creating a session without a link",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 401,
  "message": "Invalid API key",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 403,
  "message": "Payment link belongs to another organization",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

{
  "statusCode": 404,
  "message": "Payment link not found",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

Webhook: none. The credit changes no subscription state. A renewal that the credit pays sends checkout.session.completed and subscription.renewed. See Which action fires which event.

Headers

Idempotency-Key

string

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.

Maximum string length: 200

Path Parameters

string<uuid>

required

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

Body

application/json

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.

Required range: x >= 1

reason

string

required

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

Maximum string length: 200

Response

The credit was given.

A credit you gave, with both figures it changes. Money is integer minor units.

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

SDK

CLI

API Reference

Give a subscriber credit

Headers

Path Parameters

Body

Response