Managing Credits

The credits API allows you to issue, deduct, and track credits for your users. Credits are tracked per user and per credit type.

Issue Credits

Add credits to a user's account. Users are automatically created if they don't exist.

// Issue credits to a user
// Note: user_email is recommended for wallet identity
const response = await fetch(
  'https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/issue',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_your_api_key'
    },
    body: JSON.stringify({
      user_id: 'user_123',
      credit_type_id: 'your_credit_type_id',
      amount: 100,
      reason: 'Welcome bonus',
      user_email: 'user@example.com', // Recommended! Same email = same wallet
      user_name: 'John Doe'
    })
  }
);

const result = await response.json();
// { 
//   success: true, 
//   transaction_id: '...', 
//   user_id: 'user_123',
//   credit_type_id: '...',
//   amount_issued: 100,
//   new_balance: 100 
// }

Deduct Credits

Remove credits from a user's account when they consume your service.

// Deduct credits from a user
const response = await fetch(
  'https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/deduct',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_your_api_key'
    },
    body: JSON.stringify({
      user_id: 'user_123',
      credit_type_id: 'your_credit_type_id',
      amount: 25,
      reason: 'API usage'
    })
  }
);

const result = await response.json();
// { 
//   success: true, 
//   transaction_id: '...', 
//   user_id: 'user_123',
//   credit_type_id: '...',
//   amount_deducted: 25,
//   new_balance: 75 
// }

Check Balance

Query a user's current credit balance across all credit types.

// Get user's credit balance
const response = await fetch(
  'https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/balance?user_id=user_123',
  {
    headers: {
      'x-api-key': 'sk_live_your_api_key'
    }
  }
);

const result = await response.json();
// { 
//   user_id: 'user_123', 
//   balances: [{ 
//     credit_type_id: '...', 
//     credit_type_name: 'Tokens',
//     credit_type_symbol: 'TKN',
//     balance: 75 
//   }] 
// }

Safe Retries

Send an Idempotency-Key header (or an idempotency_key body field) on /issue, /deduct and /refund. If a request times out, retry it with the same key: when the first attempt went through, you get its result back with idempotent_replay: true and nothing moves twice.

• Use one key per operation, such as your job or order id (up to 255 characters)
• Keys are scoped to your project and never expire
• Reusing a key for a different request returns 409 IDEMPOTENCY_KEY_REUSED

Email-Based Identity

When issuing credits, always include the user_email parameter. This ensures users have one wallet across all your apps within the same project.

• Same email = same wallet, regardless of user_id
• Credits are automatically shared across your apps
• Users can access balances from any app using their email

Best Practices

• Always check balance before performing expensive operations
• Use reference_id to link transactions to your internal records
• Handle insufficient balance errors gracefully in your UI
• Use webhooks to sync credit changes in real-time

Your first credit is one request away.

Create a project, copy an API key, and issue a credit from your server.

Get an API key Open the dashboard

Managing Credits - cred.diy API documentation