> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# User & Credits API

> Manage user profiles, credit balance, and usage tracking

## Overview

The User & Credits API provides endpoints for managing user profiles, checking credit balance, viewing usage history, and handling billing operations.

## Base URL

```
https://api.percify.io/v1
```

## Core Endpoints

| Method | Endpoint                 | Description                    |
| ------ | ------------------------ | ------------------------------ |
| GET    | `/user/profile`          | Get current user profile       |
| PATCH  | `/user/profile`          | Update user profile            |
| GET    | `/user/credits/balance`  | Get credit balance             |
| GET    | `/user/credits/history`  | Get credit transaction history |
| GET    | `/user/usage`            | Get usage statistics           |
| POST   | `/user/credits/purchase` | Purchase credit pack           |
| GET    | `/user/tier`             | Get subscription tier info     |

## User Profile Object

```json theme={null}
{
  "id": "user_abc123",
  "email": "user@example.com",
  "username": "creative_user",
  "displayName": "Creative User",
  "avatar": "https://cdn.percify.io/avatars/user_abc123.jpg",
  "bio": "AI artist and content creator",
  "website": "https://example.com",
  "tier": "pro",
  "verified": true,
  "stats": {
    "avatarsCreated": 156,
    "videosGenerated": 42,
    "voicesCloned": 8,
    "followers": 234,
    "following": 89
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-11-25T06:30:00Z"
}
```

## Credits Object

```json theme={null}
{
  "balance": 450,
  "lifetime": {
    "earned": 50,
    "purchased": 500,
    "spent": 100
  },
  "currentMonth": {
    "earned": 0,
    "spent": 35
  },
  "tier": "pro",
  "nextRefill": "2025-12-01T00:00:00Z"
}
```

## Get User Profile

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.percify.io/v1/user/profile', {
    headers: {
      'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
    }
  });

  const profile = await response.json();
  console.log(`Username: ${profile.username}, Tier: ${profile.tier}`);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://api.percify.io/v1/user/profile',
      headers={'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'}
  )

  profile = response.json()
  print(f"Username: {profile['username']}, Tier: {profile['tier']}")
  ```

  ```bash cURL theme={null}
  curl -X GET https://api.percify.io/v1/user/profile \
    -H "Authorization: Bearer $PERCIFY_API_KEY"
  ```
</CodeGroup>

## Get Credit Balance

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.percify.io/v1/user/credits/balance', {
    headers: {
      'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
    }
  });

  const credits = await response.json();
  console.log(`Available credits: ${credits.balance}`);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://api.percify.io/v1/user/credits/balance',
      headers={'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'}
  )

  credits = response.json()
  print(f"Available credits: {credits['balance']}")
  ```

  ```bash cURL theme={null}
  curl -X GET https://api.percify.io/v1/user/credits/balance \
    -H "Authorization: Bearer $PERCIFY_API_KEY"
  ```
</CodeGroup>

## Credit Transaction History

```bash theme={null}
curl "https://api.percify.io/v1/user/credits/history?limit=50&offset=0" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

Response:

```json theme={null}
{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "debit",
      "amount": 5,
      "balance": 445,
      "description": "Avatar generation (Imagen3)",
      "resourceType": "avatar",
      "resourceId": "avatar_xyz789",
      "createdAt": "2025-11-25T06:15:00Z"
    },
    {
      "id": "txn_def456",
      "type": "credit",
      "amount": 100,
      "balance": 450,
      "description": "Credit pack purchase",
      "resourceType": "purchase",
      "resourceId": "purchase_pqr012",
      "createdAt": "2025-11-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

## Usage Statistics

```bash theme={null}
curl "https://api.percify.io/v1/user/usage?period=30d" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

Response:

```json theme={null}
{
  "period": "30d",
  "startDate": "2025-10-26T00:00:00Z",
  "endDate": "2025-11-25T23:59:59Z",
  "usage": {
    "avatars": {
      "count": 45,
      "creditsSpent": 135,
      "byModel": {
        "flux": { "count": 30, "credits": 60 },
        "imagen3": { "count": 15, "credits": 75 }
      }
    },
    "videos": {
      "count": 12,
      "creditsSpent": 420,
      "totalDuration": 96
    },
    "audio": {
      "count": 8,
      "creditsSpent": 85,
      "totalDuration": 65
    }
  },
  "totalCreditsSpent": 640,
  "averagePerDay": 21.3
}
```

## Subscription Tiers

```bash theme={null}
curl -X GET https://api.percify.io/v1/user/tier \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

Response:

```json theme={null}
{
  "currentTier": "pro",
  "tierDetails": {
    "name": "Pro",
    "monthlyCredits": 500,
    "price": 29.99,
    "features": [
      "500 credits per month",
      "Priority processing",
      "Advanced models access",
      "Batch generation",
      "Priority support"
    ],
    "limits": {
      "avatarsPerMonth": 1000,
      "videosPerMonth": 200,
      "voiceClonesTotal": 50,
      "concurrentGenerations": 5
    }
  },
  "usage": {
    "avatarsThisMonth": 45,
    "videosThisMonth": 12,
    "voiceClones": 8
  },
  "billingCycle": {
    "start": "2025-11-01T00:00:00Z",
    "end": "2025-12-01T00:00:00Z",
    "renewalDate": "2025-12-01T00:00:00Z"
  }
}
```

## Purchase Credits

```javascript theme={null}
const response = await fetch('https://api.percify.io/v1/user/credits/purchase', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    packId: 'pack_500',
    paymentMethod: 'stripe',
    returnUrl: 'https://example.com/payment/success'
  })
});

const purchase = await response.json();
console.log(`Payment URL: ${purchase.paymentUrl}`);
```

Response:

```json theme={null}
{
  "id": "purchase_abc123",
  "packId": "pack_500",
  "credits": 500,
  "price": 49.99,
  "currency": "USD",
  "paymentUrl": "https://checkout.stripe.com/...",
  "status": "pending",
  "expiresAt": "2025-11-25T07:00:00Z"
}
```

## Available Credit Packs

| Pack ID     | Credits | Price    | Bonus | Best For      |
| ----------- | ------- | -------- | ----- | ------------- |
| `pack_100`  | 100     | \$9.99   | -     | Trying out    |
| `pack_500`  | 500     | \$49.99  | +50   | Regular users |
| `pack_1000` | 1000    | \$89.99  | +150  | Power users   |
| `pack_5000` | 5000    | \$399.99 | +1000 | Professionals |

## Update User Profile

```javascript theme={null}
const response = await fetch('https://api.percify.io/v1/user/profile', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    displayName: 'Updated Name',
    bio: 'AI artist specializing in character design',
    website: 'https://newsite.com'
  })
});

const profile = await response.json();
```

## Rate Limits by Tier

| Tier       | API Requests/min | Concurrent Generations | Priority |
| ---------- | ---------------- | ---------------------- | -------- |
| Free       | 10               | 1                      | Standard |
| Pro        | 60               | 5                      | High     |
| Enterprise | 300              | 20                     | Highest  |

## Webhooks

Subscribe to credit and usage events:

```json theme={null}
{
  "event": "credits.low_balance",
  "data": {
    "balance": 25,
    "threshold": 50,
    "recommendation": "purchase_pack_500"
  },
  "timestamp": "2025-11-25T06:35:00Z"
}
```

Available events:

* `credits.low_balance` - Balance below threshold
* `credits.purchased` - Credits added
* `tier.upgraded` - Subscription upgraded
* `tier.downgraded` - Subscription downgraded
* `usage.limit_approaching` - Near tier limit

## Error Responses

```json theme={null}
{
  "error": {
    "code": "payment_failed",
    "message": "Payment processing failed. Please check your payment method.",
    "details": {
      "reason": "insufficient_funds",
      "paymentMethod": "card_****1234"
    }
  }
}
```

Common error codes:

* `invalid_pack_id` - Credit pack doesn't exist
* `payment_failed` - Payment processing error
* `tier_limit_reached` - Monthly limit exceeded
* `invalid_update` - Profile update validation failed

## Best Practices

<AccordionGroup>
  <Accordion icon="gauge" title="Monitor Usage">
    ```javascript theme={null}
    // Check balance before expensive operations
    async function checkCredits(required) {
      const response = await fetch(
        'https://api.percify.io/v1/user/credits/balance',
        {
          headers: {
            'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
          }
        }
      );
      
      const credits = await response.json();
      
      if (credits.balance < required) {
        throw new Error(
          `Insufficient credits. Required: ${required}, Available: ${credits.balance}`
        );
      }
      
      return credits.balance;
    }
    ```
  </Accordion>

  <Accordion icon="bell" title="Set Up Webhooks">
    Configure webhooks to:

    * Alert when balance is low
    * Track usage patterns
    * Automate credit purchases
    * Monitor tier limits
  </Accordion>

  <Accordion icon="coins" title="Optimize Credit Usage">
    * Use Flux model for testing (2 credits)
    * Keep videos under 5 seconds when possible
    * Reuse voice clones (5 credits once)
    * Batch similar operations
    * Monitor usage statistics regularly
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Credits Guide" icon="coins" href="/percify/credits">
    Understand pricing
  </Card>

  <Card title="Payments" icon="credit-card" href="/percify/payments">
    Billing and invoices
  </Card>

  <Card title="Usage Tracking" icon="chart-line" href="/percify/performance">
    Optimize performance
  </Card>
</CardGroup>