igny8/docs/working-docs/CORRECT-API-ENDPOINTS-REFERENCE.md

CORRECT API Endpoints Reference

Date: December 5, 2025
Purpose: Document ACTUAL working backend endpoints for frontend integration

✅ WORKING BILLING ENDPOINTS

Credit Balance

Endpoint: GET /v1/billing/credits/balance/balance/
Returns:

{
  "success": true,
  "data": {
    "credits": 100,
    "plan_credits_per_month": 100,
    "credits_used_this_month": 0,
    "credits_remaining": 100
  }
}

Credit Transactions

Endpoint: GET /v1/billing/transactions/
Returns:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "amount": 100,
        "transaction_type": "grant",
        "description": "Initial credits",
        "created_at": "2025-12-05T10:00:00Z",
        "balance_after": 100
      }
    ],
    "count": 1
  }
}

Credit Usage Logs

Endpoint: GET /v1/billing/credits/usage/
Returns:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "operation_type": "clustering",
        "credits_used": 10,
        "cost_usd": "0.10",
        "created_at": "2025-12-05T10:00:00Z"
      }
    ],
    "count": 1
  }
}

Invoices

Endpoint: GET /v1/billing/invoices/
Returns:

{
  "results": [
    {
      "id": 1,
      "invoice_number": "INV-2025-001",
      "status": "paid",
      "total_amount": "29.00",
      "created_at": "2025-12-05T10:00:00Z"
    }
  ],
  "count": 1
}

Payments

Endpoint: GET /v1/billing/payments/
Returns:

{
  "results": [
    {
      "id": 1,
      "amount": "29.00",
      "status": "succeeded",
      "payment_method": "stripe",
      "created_at": "2025-12-05T10:00:00Z"
    }
  ],
  "count": 1
}

Payment Methods

Endpoint: GET /v1/billing/payment-methods/
Returns:

{
  "results": [
    {
      "payment_method": "stripe",
      "display_name": "Credit/Debit Card",
      "is_enabled": true
    }
  ]
}

Credit Packages

Endpoint: GET /v1/billing/credit-packages/
Returns:

{
  "results": [
    {
      "id": 1,
      "name": "Starter Pack",
      "credits": 500,
      "price": "9.00",
      "is_active": true
    }
  ],
  "count": 1
}

✅ WORKING ACCOUNT ENDPOINTS

Account Settings

Endpoint: GET /v1/account/settings/
Returns:

{
  "id": 1,
  "name": "My Account",
  "slug": "my-account",
  "billing_address_line1": "123 Main St",
  "billing_city": "New York",
  "credit_balance": 100,
  "created_at": "2025-01-01T00:00:00Z"
}

Update Account Settings

Endpoint: PATCH /v1/account/settings/
Body:

{
  "name": "Updated Account Name",
  "billing_address_line1": "456 New St"
}

Team Members

Endpoint: GET /v1/account/team/
Returns:

{
  "results": [
    {
      "id": 1,
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "is_staff": false,
      "date_joined": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

Usage Analytics

Endpoint: GET /v1/account/usage/analytics/
Query Params: ?days=30
Returns:

{
  "period_days": 30,
  "current_balance": 100,
  "usage_by_type": [
    {
      "transaction_type": "deduction",
      "total": -50,
      "count": 5
    }
  ],
  "daily_usage": [
    {
      "date": "2025-12-05",
      "usage": 10,
      "purchases": 0,
      "net": -10
    }
  ],
  "total_usage": 50,
  "total_purchases": 0
}

⚠️ CORRECT DATA STRUCTURE FOR PAGES

AccountBillingPage.tsx

Should use:

• getCreditBalance() → /v1/billing/credits/balance/balance/
• getInvoices() → /v1/billing/invoices/
• getPayments() → /v1/billing/payments/

Data fields to use:

creditBalance.credits  // NOT balance
creditBalance.plan_credits_per_month  // NOT monthly_credits
creditBalance.credits_used_this_month  // NEW field

AccountSettingsPage.tsx

Should use:

• getAccountSettings() → /v1/account/settings/
• updateAccountSettings(data) → PATCH /v1/account/settings/

TeamManagementPage.tsx

Should use:

• getTeamMembers() → /v1/account/team/
• inviteTeamMember(email) → POST /v1/account/team/
• removeTeamMember(id) → DELETE /v1/account/team/{id}/

UsageAnalyticsPage.tsx

Should use:

• getUsageAnalytics(days) → /v1/account/usage/analytics/?days=30

Data fields to use:

analytics.current_balance
analytics.usage_by_type  // Array with transaction_type, total, count
analytics.daily_usage    // Array with date, usage, purchases, net
analytics.total_usage
analytics.total_purchases

PurchaseCreditsPage.tsx

Should use:

• getCreditPackages() → /v1/billing/credit-packages/
• getPaymentMethods() → /v1/billing/payment-methods/
• purchaseCreditPackage(data) → POST /v1/billing/credit-packages/{id}/purchase/

🔑 KEY POINTS

1. Account Relationship: All endpoints automatically filter by the logged-in user's account. The backend middleware sets request.account from the JWT token.

2. Unified Response Format: All endpoints return data in the format:

   {
     "success": true,
     "data": { ... }
   }
   

   The fetchAPI function in services/api.ts automatically extracts the data field.

3. Field Names: Backend uses specific field names that MUST match in frontend:

   • credits (NOT balance)
   • plan_credits_per_month (NOT monthly_credits)
   • credits_used_this_month (NEW)
   • credits_remaining (NEW)

4. No Fake Data: Pages must load real data from these endpoints. NO placeholder data.

5. Error Handling: If endpoint returns 404, the backend route is not registered. Check backend/igny8_core/urls.py and restart backend container.

🛠️ FRONTEND FIX CHECKLIST

• Update billing.api.ts to use correct endpoints
• Update type interfaces to match backend response
• Fix AccountBillingPage to use credits, plan_credits_per_month, credits_used_this_month
• Fix UsageAnalyticsPage to use usage_by_type, daily_usage structure
• Fix PurchaseCreditsPage to call correct payment-methods endpoint
• Fix TeamManagementPage to handle optional date_joined field
• Fix AccountSettingsPage to load from /v1/account/settings/
• Remove all placeholder/fake data
• Test all pages with real backend data