API Overview

DonutMe provides a RESTful API for managing projects, payment plans, transactions, and webhooks.

Base URL

https://api.donutme.xyz/api/v1

Authentication

API requests can be authenticated in three ways:

Session cookie (for browser-based access): the dashboard authenticates with the better-auth.session_token cookie, sent automatically by the browser (requests use credentials: include). No Authorization header is used for session auth.
API key (for server-to-server access) — Authorization: Bearer dm_...:

Shell

curl -H "Authorization: Bearer dm_your_key_here" \
  https://api.donutme.xyz/api/v1/projects/{projectId}/transactions

OAuth 2.1 access token (for third-party apps) — Authorization: Bearer dm_at_...:

Shell

curl -H "Authorization: Bearer dm_at_your_access_token" \
  https://api.donutme.xyz/api/v1/projects/{projectId}/transactions

See Authentication for details on obtaining tokens and API keys.

Response Format

All responses follow a unified envelope:

Success Response

JSON

{
  "success": true,
  "statusCode": 200,
  "message": "OK",
  "data": {},
  "meta": {
    "timestamp": "2026-04-08T10:00:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/projects"
  }
}

Paginated Response

JSON

{
  "success": true,
  "statusCode": 200,
  "message": "OK",
  "data": [],
  "meta": {
    "timestamp": "2026-04-08T10:00:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/transactions",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

Error Response

JSON

{
  "success": false,
  "statusCode": 422,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "amount", "message": "Must be a positive number" }
    ]
  },
  "meta": {
    "timestamp": "2026-04-08T10:00:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/payment-plans"
  }
}

Rate Limiting

API requests are rate-limited per session or API key:

Tier	Limit	Usage
Relaxed	60 req/min	List/get operations
Semi-Relaxed	30 req/min	Standard write operations
Standard	20 req/min	General endpoints
Moderate	10 req/min	Sensitive operations
Strict	5 req/min	Checkout session creation, password changes

When rate limited, responses return HTTP 429 with a Retry-After header (in seconds).

API Sections

Authentication — Session management, passkeys
Payments — Transactions, payment plans, checkout sessions