Customers

/v1/customers — tus clientes finales. Ver también el concepto Cliente.

El objeto Customer

{
  "id": "cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  "email": "cliente@ejemplo.com",
  "name": "María Pérez",
  "external_id": "user_9182",
  "default_payment_method_id": "pm_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  "created_at": "2026-08-24T15:00:00Z"
}

Campo	Tipo	Descripción
`id`	string	Identificador único
`email`	string	Correo del cliente
`name`	string \| null	Nombre del cliente
`external_id`	string \| null	Tu propio identificador interno para este cliente
`default_payment_method_id`	string \| null	Método de pago por defecto
`created_at`	datetime	Fecha de creación

Crear un cliente

POST /v1/customers

Request body

{ "email": "cliente@ejemplo.com", "name": "María Pérez", "external_id": "user_9182" }

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Correo del cliente
`name`	string	No	Nombre del cliente
`external_id`	string	No	Tu identificador interno para este cliente

curl -X POST https://api.rekurra.dev/v1/customers \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "email": "cliente@ejemplo.com", "name": "María Pérez" }'

const res = await fetch("https://api.rekurra.dev/v1/customers", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "cliente@ejemplo.com", name: "María Pérez" }),
});
const customer = await res.json();

import requests
 
res = requests.post(
    "https://api.rekurra.dev/v1/customers",
    headers={
        "Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={"email": "cliente@ejemplo.com", "name": "María Pérez"},
)
customer = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "email": "cliente@ejemplo.com",
      "name": "María Pérez"
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/customers"))
    .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 = """
    {
      "email": "cliente@ejemplo.com",
      "name": "María Pérez"
    }
    """;
var content = new StringContent(json, Encoding.UTF8, "application/json");
 
var response = await http.PostAsync("https://api.rekurra.dev/v1/customers", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response — `201 Created`

Devuelve el objeto Customer creado.

Errores posibles

Status	`error.type`	Causa
`400`	`invalid_request`	`email` faltante o con formato inválido
`401`	`authentication_error`	API key inválida o ausente

Listar clientes

GET /v1/customers

Filtro opcional ?email= (búsqueda exacta), más paginación estándar (?limit=, ?starting_after=).

curl "https://api.rekurra.dev/v1/customers?email=cliente@ejemplo.com" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

const res = await fetch(
  "https://api.rekurra.dev/v1/customers?email=cliente@ejemplo.com",
  { headers: { Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" } }
);
const { data } = await res.json();

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/customers",
    params={"email": "cliente@ejemplo.com"},
    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/customers?email=cliente@ejemplo.com"))
    .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/customers?email=cliente@ejemplo.com");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Obtener un cliente

GET /v1/customers/{id}

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

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

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
    headers={"Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"},
)
customer = 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/customers/cus_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/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Errores posibles

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

Actualizar un cliente

PATCH /v1/customers/{id}

curl -X PATCH https://api.rekurra.dev/v1/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2 \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "name": "María Pérez Gómez" }'

const res = await fetch(
  "https://api.rekurra.dev/v1/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "María Pérez Gómez" }),
  }
);
const customer = await res.json();

import requests
 
res = requests.patch(
    "https://api.rekurra.dev/v1/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
    headers={
        "Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={"name": "María Pérez Gómez"},
)
customer = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "name": "María Pérez Gómez"
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/customers/cus_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 = """
    {
      "name": "María Pérez Gómez"
    }
    """;
var content = new StringContent(json, Encoding.UTF8, "application/json");
 
var response = await http.PatchAsync("https://api.rekurra.dev/v1/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Eliminar un cliente

DELETE /v1/customers/{id}

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

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

import requests
 
requests.delete(
    "https://api.rekurra.dev/v1/customers/cus_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/customers/cus_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/customers/cus_01HZXK7QJ5M8Z9X2R3TVQ7A1B2");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Errores posibles

Status	`error.type`	Causa
`404`	`invalid_request`	El cliente no existe
`409`	`invalid_request`	El cliente tiene suscripciones activas que impiden su eliminación

Addons Payment methods

Customers

El objeto Customer

Crear un cliente

Request body

Response — 201 Created

Errores posibles

Listar clientes

Obtener un cliente

Errores posibles

Actualizar un cliente

Eliminar un cliente

Errores posibles

Response — `201 Created`