Addons

/v1/addons — productos recurrentes reutilizables que se agregan a una suscripción existente para aumentar su monto de cobro por periodo. A diferencia de un Plan, un addon no se suscribe directamente: se define una sola vez en tu catálogo y luego se adjunta a una o varias suscripciones usando los endpoints de Subscriptions.

El objeto Addon

{
  "id": "addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  "code": "soporte-prioritario",
  "name": "Soporte prioritario",
  "price_monthly_cents": 1500000,
  "price_annual_cents": 15000000,
  "description": "Atención en menos de 1 hora hábil",
  "active": true,
  "created_at": "2026-09-12T15:00:00Z"
}

Campo	Tipo	Descripción
`id`	string	Identificador único del addon
`code`	string	Código único y legible
`name`	string	Nombre visible del addon
`price_monthly_cents`	integer	Precio mensual, en centavos COP
`price_annual_cents`	integer \| null	Precio anual, en centavos COP
`description`	string \| null	Descripción libre
`active`	boolean	Si el addon puede adjuntarse a suscripciones
`created_at`	datetime	Fecha de creación (ISO-8601 UTC)

Crear un addon

POST /v1/addons

Request body

{
  "code": "soporte-prioritario",
  "name": "Soporte prioritario",
  "price_monthly_cents": 1500000,
  "price_annual_cents": 15000000,
  "description": "Atención en menos de 1 hora hábil",
  "active": true
}

Campo	Tipo	Requerido	Descripción
`code`	string	Sí	Código único por desarrollador y entorno
`name`	string	Sí	Nombre visible
`price_monthly_cents`	integer	Sí	Precio mensual en centavos COP
`price_annual_cents`	integer	No	Precio anual en centavos COP; si se omite se usa `price_monthly_cents * 12` en ciclos anuales
`description`	string	No	Descripción libre
`active`	boolean	No	Por defecto `true`

Response — `201 Created`

Devuelve el objeto Addon creado.

curl -X POST https://api.rekurra.dev/v1/addons \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "soporte-prioritario",
    "name": "Soporte prioritario",
    "price_monthly_cents": 1500000
  }'

const res = await fetch("https://api.rekurra.dev/v1/addons", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    code: "soporte-prioritario",
    name: "Soporte prioritario",
    price_monthly_cents: 1500000,
  }),
});
const addon = await res.json();

import requests
 
res = requests.post(
    "https://api.rekurra.dev/v1/addons",
    headers={
        "Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={
        "code": "soporte-prioritario",
        "name": "Soporte prioritario",
        "price_monthly_cents": 1500000,
    },
)
addon = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "code": "soporte-prioritario",
      "name": "Soporte prioritario",
      "price_monthly_cents": 1500000
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/addons"))
    .header("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Text;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var json = """
    {
      "code": "soporte-prioritario",
      "name": "Soporte prioritario",
      "price_monthly_cents": 1500000
    }
    """;
var content = new StringContent(json, Encoding.UTF8, "application/json");
 
var response = await http.PostAsync("https://api.rekurra.dev/v1/addons", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Errores posibles

Status	`error.type`	Causa
`400`	`invalid_request`	Falta `code` o `name`, o `price_monthly_cents` no es positivo
`401`	`authentication_error`	API key inválida o ausente
`409`	`invalid_request`	Ya existe un addon con ese `code`

Listar addons

GET /v1/addons

Soporta paginación estándar: ?limit= (default 25, máx 100) y ?starting_after=<id>.

curl "https://api.rekurra.dev/v1/addons?limit=25" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

const res = await fetch("https://api.rekurra.dev/v1/addons?limit=25", {
  headers: { Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" },
});
const { data, has_more, next_cursor } = await res.json();

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/addons",
    params={"limit": 25},
    headers={"Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"},
)
body = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/addons?limit=25"))
    .header("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX")
    .GET()
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var response = await http.GetAsync("https://api.rekurra.dev/v1/addons?limit=25");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response — `200 OK`

{ "data": [ /* Addon[] */ ], "has_more": false, "next_cursor": null }

Obtener un addon

GET /v1/addons/{id}

curl https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2 \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

const res = await fetch(
  "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  { headers: { Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" } }
);
const addon = await res.json();

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
    headers={"Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"},
)
addon = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2"))
    .header("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX")
    .GET()
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var response = await http.GetAsync("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Errores posibles

Status	`error.type`	Causa
`404`	`invalid_request`	El addon no existe o no pertenece a tu cuenta

Actualizar un addon

PATCH /v1/addons/{id}

Acepta cualquier subconjunto de los campos de creación (excepto code).

curl -X PATCH https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2 \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "price_monthly_cents": 2000000 }'

const res = await fetch(
  "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ price_monthly_cents: 2000000 }),
  }
);
const addon = await res.json();

import requests
 
res = requests.patch(
    "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
    headers={
        "Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={"price_monthly_cents": 2000000},
)
addon = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "price_monthly_cents": 2000000
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2"))
    .header("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Text;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var json = """
    {
      "price_monthly_cents": 2000000
    }
    """;
var content = new StringContent(json, Encoding.UTF8, "application/json");
 
var response = await http.PatchAsync("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Errores posibles

Status	`error.type`	Causa
`400`	`invalid_request`	Campo con formato inválido
`404`	`invalid_request`	El addon no existe

Desactivar un addon

DELETE /v1/addons/{id}

Desactivación suave: marca active: false. Las suscripciones que ya tienen este addon adjunto no se ven afectadas, pero ya no podrá adjuntarse a nuevas suscripciones. No elimina el historial de uso.

curl -X DELETE https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2 \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

await fetch(
  "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" },
  }
);

import requests
 
requests.delete(
    "https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
    headers={"Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"},
)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2"))
    .header("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX")
    .DELETE()
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var response = await http.DeleteAsync("https://api.rekurra.dev/v1/addons/addon_01HZXK7QJ5M8Z9X2R3TVQ7A1B2");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response — `200 OK`

Devuelve el objeto Addon con active: false.

Plans Customers

Addons

El objeto Addon

Crear un addon

Request body

Response — 201 Created

Errores posibles

Listar addons

Response — 200 OK

Obtener un addon

Errores posibles

Actualizar un addon

Errores posibles

Desactivar un addon

Response — 200 OK

Response — `201 Created`

Response — `200 OK`

Response — `200 OK`