API Reference

Authentication

All protected endpoints require your API key sent as an HTTP header. You get your key when you register.

Base URL

All requests go to:

GET /health

Public. Check that the API is up. No authentication required.

curl https://api.comorando.com/health

Response

POST /api-keys/register

Public. Create an organization and get your API key in one step. The key is shown once — save it immediately.

curl -X POST https://api.comorando.com/api-keys/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","name":"Acme Inc"}'

const res = await fetch('https://api.comorando.com/api-keys/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'you@example.com', name: 'Acme Inc' })
});
const { organizationId, apiKey, plan } = await res.json();
// Save apiKey — it's only shown once

Response 201

POST /decisions

Send a failed payment or subscription event. Comorando analyzes the context and automatically decides: whether to retry the payment, when to retry, whether to grant a grace period, and whether to escalate the issue. Execution happens automatically after the decision. Response is immediate (<50ms).

Example: A $79 payment fails due to insufficient funds. Comorando schedules a retry and helps prevent a potential churn event.

curl -X POST https://api.comorando.com/decisions \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: ck_your_key_here' \
  -d '{
    "event_type": "payment.failed",
    "event_id": "paypal-evt-abc123",
    "data": {
      "customer_email": "user@example.com",
      "amount": 79.00,
      "currency": "USD",
      "failure_reason": "insufficient_funds"
    }
  }'

const res = await fetch('https://api.comorando.com/decisions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.COMORANDO_API_KEY
  },
  body: JSON.stringify({
    event_type: 'payment.failed',
    event_id: webhookEvent.id,   // ensures exactly-once
    data: webhookEvent
  })
});
const { id, status, correlation_id } = await res.json();

Response 201

Retry Guidelines

Comorando's default retry schedule is designed to comply with PayPal AUP section 4.3 and equivalent processor policies. You may customize intervals via your decision configuration, but must remain within your processor's acceptable use boundaries.

Supported Payment Providers

Configure your provider's webhook URL to point to the corresponding endpoint below. Add your provider credentials to your environment variables.

Event types

Use these as the event_type field when submitting decisions.

Error codes

Want to use Comorando in production? See pricing →

Need help? hello@comorando.com