Update auto top-up

curl --request PATCH \
  --url https://commet.co/api/v1/subscriptions/{id}/auto-top-up \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "enabled": true,
  "threshold": 1073741823,
  "quantity": 1073741824,
  "amount": 1073741824,
  "maxPerPeriod": 50
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    enabled: true,
    threshold: 1073741823,
    quantity: 1073741824,
    amount: 1073741824,
    maxPerPeriod: 50
  })
};

fetch('https://commet.co/api/v1/subscriptions/{id}/auto-top-up', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://commet.co/api/v1/subscriptions/{id}/auto-top-up"

payload = {
    "enabled": True,
    "threshold": 1073741823,
    "quantity": 1073741824,
    "amount": 1073741824,
    "maxPerPeriod": 50
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://commet.co/api/v1/subscriptions/{id}/auto-top-up"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"threshold\": 1073741823,\n  \"quantity\": 1073741824,\n  \"amount\": 1073741824,\n  \"maxPerPeriod\": 50\n}")

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

	req.Header.Add("x-api-key", "<api-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.patch("https://commet.co/api/v1/subscriptions/{id}/auto-top-up")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"threshold\": 1073741823,\n  \"quantity\": 1073741824,\n  \"amount\": 1073741824,\n  \"maxPerPeriod\": 50\n}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://commet.co/api/v1/subscriptions/{id}/auto-top-up",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'enabled' => true,
    'threshold' => 1073741823,
    'quantity' => 1073741824,
    'amount' => 1073741824,
    'maxPerPeriod' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

{
  "enabled": true,
  "threshold": 5,
  "quantity": 50,
  "maxPerPeriod": 10,
  "status": "active",
  "topUpsThisPeriod": 1,
  "periodResetsAt": "2026-10-07T12:00:00.000Z",
  "lastFailure": null,
  "object": "subscription_auto_top_up",
  "livemode": false
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "The request contains an invalid parameter.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "A valid API key is required.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "forbidden",
    "message": "You do not have permission to perform this operation.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this idempotency key is still being processed.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "internal_error",
    "message": "An unexpected error occurred while processing the request.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "idempotency_unavailable",
    "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md"
  }
}

Subscriptions

Update auto top-up

Turn automatic top-ups on or off and set the threshold, the size of each top-up and the maximum top-ups per period. Send only the fields that change. On a credits plan each top-up buys quantity credits; on a balance plan it adds amount in minor units of the subscription currency, plus tax, and threshold is in the same minor units. Enabling requires a plan that sells credits or has balance top-ups on. The size must be at least the plan’s minimum when auto top-up is enabled or when the size changes, so turning it off keeps working after the minimum rises. Saving it enabled resumes a paused auto top-up.

PATCH

subscriptions

{id}

auto-top-up

Update auto top-up

curl --request PATCH \
  --url https://commet.co/api/v1/subscriptions/{id}/auto-top-up \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "enabled": true,
  "threshold": 1073741823,
  "quantity": 1073741824,
  "amount": 1073741824,
  "maxPerPeriod": 50
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    enabled: true,
    threshold: 1073741823,
    quantity: 1073741824,
    amount: 1073741824,
    maxPerPeriod: 50
  })
};

fetch('https://commet.co/api/v1/subscriptions/{id}/auto-top-up', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://commet.co/api/v1/subscriptions/{id}/auto-top-up"

payload = {
    "enabled": True,
    "threshold": 1073741823,
    "quantity": 1073741824,
    "amount": 1073741824,
    "maxPerPeriod": 50
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://commet.co/api/v1/subscriptions/{id}/auto-top-up"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"threshold\": 1073741823,\n  \"quantity\": 1073741824,\n  \"amount\": 1073741824,\n  \"maxPerPeriod\": 50\n}")

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

	req.Header.Add("x-api-key", "<api-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.patch("https://commet.co/api/v1/subscriptions/{id}/auto-top-up")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"threshold\": 1073741823,\n  \"quantity\": 1073741824,\n  \"amount\": 1073741824,\n  \"maxPerPeriod\": 50\n}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://commet.co/api/v1/subscriptions/{id}/auto-top-up",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'enabled' => true,
    'threshold' => 1073741823,
    'quantity' => 1073741824,
    'amount' => 1073741824,
    'maxPerPeriod' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

{
  "enabled": true,
  "threshold": 5,
  "quantity": 50,
  "maxPerPeriod": 10,
  "status": "active",
  "topUpsThisPeriod": 1,
  "periodResetsAt": "2026-10-07T12:00:00.000Z",
  "lastFailure": null,
  "object": "subscription_auto_top_up",
  "livemode": false
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "The request contains an invalid parameter.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "A valid API key is required.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "forbidden",
    "message": "You do not have permission to perform this operation.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this idempotency key is still being processed.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "internal_error",
    "message": "An unexpected error occurred while processing the request.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "idempotency_unavailable",
    "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md"
  }
}

This reference describes API version 2026-08-27. Send Commet-Version: 2026-08-27 with your request.

Autorizaciones

x-api-key

string

header

requerido

Encabezados

Idempotency-Key

string

Unique key used to safely retry this write for 24 hours without applying it twice.

Required string length: 1 - 200

Commet-Version

string

predeterminado:2026-08-27

API version used by this reference. Send this header to select this contract explicitly.

Parámetros de ruta

string

requerido

Cuerpo

application/json

enabled

boolean

threshold

integer

Rango requerido: 0 <= x <= 2147483647

quantity

integer

Credits each top-up buys. Credits plans only.

Rango requerido: 1 <= x <= 2147483647

amount

integer

Minor units of the subscription currency each top-up adds. Balance plans only.

Rango requerido: 1 <= x <= 2147483647

maxPerPeriod

integer

Rango requerido: 1 <= x <= 100

Respuesta

Success

enabled

boolean

requerido

Whether top-ups run automatically: credits bought on a credits plan, balance added on a balance plan. Always false when the plan does not sell credits or has balance top-ups turned off.

threshold

integer | null

requerido

The available amount at or below which a top-up runs, or null when never configured: credits (plan plus purchased) on a credits plan, minor units of the subscription currency (plan plus purchased balance) on a balance plan.

Rango requerido: -9007199254740991 <= x <= 9007199254740991

quantity

integer | null

requerido

Credits each top-up buys on a credits plan, or null when never configured or on a balance plan.

Rango requerido: -9007199254740991 <= x <= 9007199254740991

amount

integer | null

requerido

Minor units of the subscription currency each top-up adds on a balance plan, charged plus tax, or null when never configured or on a credits plan.

Rango requerido: -9007199254740991 <= x <= 9007199254740991

maxPerPeriod

integer | null

requerido

Maximum top-ups per renewal period, or null when never configured.

Rango requerido: -9007199254740991 <= x <= 9007199254740991

status

enum<string>

requerido

active tops up when the available amount reaches the threshold; paused stops after three consecutive failed top-ups, or after one whose charge could not be refunded, until the payment method changes, a credit purchase or balance top-up succeeds or it is saved enabled again; off tops up nothing.

Opciones disponibles:

active,

paused,

off

topUpsThisPeriod

integer

requerido

Top-ups made in the current renewal period.

Rango requerido: -9007199254740991 <= x <= 9007199254740991

periodResetsAt

string<date-time> | null

requerido

When the top-up count of the period resets, or null before the subscription starts its first period.

lastFailure

object | null

requerido

The last top-up that failed, or null when none has failed.

Show child attributes

object

string

requerido

Allowed value: "subscription_auto_top_up"

livemode

boolean

requerido