Get Usage - WiseYield

curl -X GET https://www.wiseyield.co/api/billing/usage \
  -H "Authorization: Bearer wy_YOUR_API_KEY"

const response = await fetch(
  'https://www.wiseyield.co/api/billing/usage',
  {
    headers: {
      'Authorization': 'Bearer wy_YOUR_API_KEY'
    }
  }
);

const usage = await response.json();

console.log(`Farms: ${usage.farmsCount}`);
console.log(`AI Requests: ${usage.aiRequestsThisMonth}`);

import requests

response = requests.get(
    'https://www.wiseyield.co/api/billing/usage',
    headers={'Authorization': 'Bearer wy_YOUR_API_KEY'}
)

usage = response.json()

print(f"Farms: {usage['farmsCount']}")
print(f"AI Requests: {usage['aiRequestsThisMonth']}")

{
  "farmsCount": 3,
  "aiRequestsThisMonth": 127
}

{
  "farmsCount": 0,
  "aiRequestsThisMonth": 0
}

{
  "error": "Unauthorized"
}

{
  "error": "Failed to fetch usage"
}

GET

api

billing

usage

curl -X GET https://www.wiseyield.co/api/billing/usage \
  -H "Authorization: Bearer wy_YOUR_API_KEY"

const response = await fetch(
  'https://www.wiseyield.co/api/billing/usage',
  {
    headers: {
      'Authorization': 'Bearer wy_YOUR_API_KEY'
    }
  }
);

const usage = await response.json();

console.log(`Farms: ${usage.farmsCount}`);
console.log(`AI Requests: ${usage.aiRequestsThisMonth}`);

import requests

response = requests.get(
    'https://www.wiseyield.co/api/billing/usage',
    headers={'Authorization': 'Bearer wy_YOUR_API_KEY'}
)

usage = response.json()

print(f"Farms: {usage['farmsCount']}")
print(f"AI Requests: {usage['aiRequestsThisMonth']}")

{
  "farmsCount": 3,
  "aiRequestsThisMonth": 127
}

{
  "farmsCount": 0,
  "aiRequestsThisMonth": 0
}

{
  "error": "Unauthorized"
}

{
  "error": "Failed to fetch usage"
}

Endpoint

GET https://www.wiseyield.co/api/billing/usage

Authentication

Requires a valid API key with billing:read scope.

Response

Returns usage statistics object.

farmsCount

number

Number of active farms owned by user

aiRequestsThisMonth

number

Number of successful AI requests made this billing period (current month)

curl -X GET https://www.wiseyield.co/api/billing/usage \
  -H "Authorization: Bearer wy_YOUR_API_KEY"

const response = await fetch(
  'https://www.wiseyield.co/api/billing/usage',
  {
    headers: {
      'Authorization': 'Bearer wy_YOUR_API_KEY'
    }
  }
);

const usage = await response.json();

console.log(`Farms: ${usage.farmsCount}`);
console.log(`AI Requests: ${usage.aiRequestsThisMonth}`);

import requests

response = requests.get(
    'https://www.wiseyield.co/api/billing/usage',
    headers={'Authorization': 'Bearer wy_YOUR_API_KEY'}
)

usage = response.json()

print(f"Farms: {usage['farmsCount']}")
print(f"AI Requests: {usage['aiRequestsThisMonth']}")

{
  "farmsCount": 3,
  "aiRequestsThisMonth": 127
}

{
  "farmsCount": 0,
  "aiRequestsThisMonth": 0
}

{
  "error": "Unauthorized"
}

{
  "error": "Failed to fetch usage"
}

Errors

401

error

Unauthorized - Missing or invalid API key

500

error

Internal Server Error - Failed to fetch usage statistics

Usage Metrics Explained

farmsCount

Definition: Number of active farms user owns (not deleted)
Excludes: Soft-deleted farms, farms user is member of but doesn’t own
Updates: Real-time (reflects current database state)

aiRequestsThisMonth

Definition: Count of successful AI requests made since billing period start
Billing Period: Calendar month (resets on 1st of month)
Includes: Only completed/successful requests
Excludes: Failed requests, pending requests, requests from previous months

Plan Limits

Usage limits by plan tier:

Seed Plan (€22/month)

Farms: 1 farm
AI Requests: 50/month

Sprout Plan (€49/month)

Farms: 3 farms
AI Requests: 200/month

Harvest Plan (€89/month) ⭐

Farms: 7 farms
AI Requests: 500/month

Grove Plan (€149/month)

Farms: 15 farms
AI Requests: 1,000/month

Summit Plan (€299+/month)

Farms: Unlimited
AI Requests: Unlimited

Use Cases

Check Usage Against Limits

async function checkUsageLimits() {
  const [usageResponse, subscriptionResponse] = await Promise.all([
    fetch('/api/billing/usage', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }),
    fetch('/api/billing/subscription', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    })
  ]);

  const usage = await usageResponse.json();
  const { subscription } = await subscriptionResponse.json();

  const plan = subscription?.plan || 'expired';

  const limits = {
    expired: { farms: 1, aiRequests: 50 },
    seed: { farms: 1, aiRequests: 50 },
    sprout: { farms: 3, aiRequests: 200 },
    harvest: { farms: 7, aiRequests: 500 },
    grove: { farms: 15, aiRequests: 1000 },
    summit: { farms: Infinity, aiRequests: Infinity }
  };

  const planLimits = limits[plan];

  return {
    farms: {
      used: usage.farmsCount,
      limit: planLimits.farms,
      percentage: (usage.farmsCount / planLimits.farms) * 100,
      remaining: planLimits.farms - usage.farmsCount
    },
    aiRequests: {
      used: usage.aiRequestsThisMonth,
      limit: planLimits.aiRequests,
      percentage: (usage.aiRequestsThisMonth / planLimits.aiRequests) * 100,
      remaining: planLimits.aiRequests - usage.aiRequestsThisMonth
    }
  };
}

// Usage
const limits = await checkUsageLimits();
if (limits.farms.percentage >= 80) {
  showUpgradePrompt('farms');
}

Show Usage Dashboard

async function getUsageDashboard() {
  const response = await fetch('/api/billing/usage', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const usage = await response.json();

  return {
    farmsCount: usage.farmsCount,
    aiRequestsThisMonth: usage.aiRequestsThisMonth,
    aiRequestsRemaining: 500 - usage.aiRequestsThisMonth, // For harvest plan
    resetDate: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1)
  };
}

Check Before Creating Resource

async function canCreateFarm() {
  const [usageResponse, subscriptionResponse] = await Promise.all([
    fetch('/api/billing/usage', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }),
    fetch('/api/billing/subscription', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    })
  ]);

  const usage = await usageResponse.json();
  const { subscription } = await subscriptionResponse.json();

  const plan = subscription?.plan || 'expired';

  const farmLimits = {
    expired: 1,
    seed: 1,
    sprout: 3,
    harvest: 7,
    grove: 15,
    summit: Infinity
  };

  const limit = farmLimits[plan];
  const canCreate = usage.farmsCount < limit;

  if (!canCreate) {
    return {
      allowed: false,
      reason: `You've reached the ${plan} plan limit of ${limit} farm(s). Upgrade to create more farms.`,
      currentUsage: usage.farmsCount,
      limit
    };
  }

  return { allowed: true };
}

// Usage
const canCreate = await canCreateFarm();
if (!canCreate.allowed) {
  toast.error(canCreate.reason);
  showUpgradeDialog();
}

Monitor AI Request Usage

async function checkAiRequestQuota() {
  const response = await fetch('/api/billing/usage', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const usage = await response.json();

  const limit = 500; // Harvest plan
  const used = usage.aiRequestsThisMonth;
  const percentage = (used / limit) * 100;

  return {
    used,
    limit,
    remaining: limit - used,
    percentage,
    willResetOn: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1),
    isNearLimit: percentage >= 80,
    isOverLimit: used >= limit
  };
}

// Usage
const quota = await checkAiRequestQuota();
if (quota.isNearLimit) {
  toast.warning(`You've used ${quota.percentage.toFixed(0)}% of your AI requests`);
}

Best Practices

Check Before Actions: Verify usage limits before allowing users to create farms or make AI requests.

Show Progress Bars: Display usage as percentage of limit with visual progress bars.

Warn at 80%: Alert users when they reach 80% of any limit to avoid surprises.

Display Reset Date: Show when AI request counter resets (1st of next month).

Monthly Reset: AI request count resets on 1st of each month, not on subscription anniversary.

Real-Time Data: Usage numbers are real-time. Cache carefully to avoid stale data blocking actions.

Soft Limits: Exceeding limits may trigger soft blocks. Always check before resource-intensive operations.

Integration Examples

Usage Dashboard Card

function UsageDashboardCard() {
  const [usage, setUsage] = useState(null);
  const [subscription, setSubscription] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadData() {
      try {
        const [usageRes, subRes] = await Promise.all([
          fetch('/api/billing/usage', {
            headers: { 'Authorization': `Bearer ${apiKey}` }
          }),
          fetch('/api/billing/subscription', {
            headers: { 'Authorization': `Bearer ${apiKey}` }
          })
        ]);

        const usageData = await usageRes.json();
        const { subscription } = await subRes.json();

        setUsage(usageData);
        setSubscription(subscription);
      } finally {
        setLoading(false);
      }
    }

    loadData();
  }, []);

  if (loading) return <div>Loading...</div>;

  const plan = subscription?.plan || 'expired';

  const limits = {
    expired: { farms: 1, aiRequests: 50 },
    seed: { farms: 1, aiRequests: 50 },
    sprout: { farms: 3, aiRequests: 200 },
    harvest: { farms: 7, aiRequests: 500 },
    grove: { farms: 15, aiRequests: 1000 },
    summit: { farms: Infinity, aiRequests: Infinity }
  };

  const planLimits = limits[plan];

  return (
    <div className="usage-card">
      <h3>Usage This Month</h3>

      <div className="usage-metric">
        <label>Farms</label>
        <ProgressBar
          value={usage.farmsCount}
          max={planLimits.farms}
          label={`${usage.farmsCount} / ${planLimits.farms === Infinity ? '∞' : planLimits.farms}`}
        />
      </div>

      <div className="usage-metric">
        <label>AI Requests</label>
        <ProgressBar
          value={usage.aiRequestsThisMonth}
          max={planLimits.aiRequests}
          label={`${usage.aiRequestsThisMonth} / ${planLimits.aiRequests === Infinity ? '∞' : planLimits.aiRequests}`}
        />

        <p className="reset-info">
          Resets: {new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1).toLocaleDateString()}
        </p>
      </div>

      {(usage.farmsCount >= planLimits.farms || usage.aiRequestsThisMonth >= planLimits.aiRequests) && (
        <div className="upgrade-prompt">
          <p>You've reached your plan limits</p>
          <button onClick={() => router.push('/pricing')}>
            Upgrade Plan
          </button>
        </div>
      )}
    </div>
  );
}

Usage Progress Bar

function UsageProgressBar({ used, limit, label }) {
  const percentage = limit === Infinity ? 0 : (used / limit) * 100;

  const getColor = () => {
    if (percentage >= 100) return 'red';
    if (percentage >= 80) return 'orange';
    return 'green';
  };

  return (
    <div className="progress-bar">
      <div className="progress-label">
        <span>{label}</span>
        <span>{used} / {limit === Infinity ? '∞' : limit}</span>
      </div>

      <div className="progress-track">
        <div
          className={`progress-fill bg-${getColor()}`}
          style={{ width: `${Math.min(percentage, 100)}%` }}
        />
      </div>

      <div className="progress-percentage">
        {limit === Infinity ? 'Unlimited' : `${percentage.toFixed(0)}%`}
      </div>
    </div>
  );
}

Usage Guard Hook

function useUsageGuard(resourceType) {
  const [canCreate, setCanCreate] = useState(false);
  const [loading, setLoading] = useState(true);
  const [reason, setReason] = useState(null);

  useEffect(() => {
    async function checkUsage() {
      const [usageRes, subRes] = await Promise.all([
        fetch('/api/billing/usage', {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        }),
        fetch('/api/billing/subscription', {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        })
      ]);

      const usage = await usageRes.json();
      const { subscription } = await subRes.json();

      const plan = subscription?.plan || 'expired';

      const limits = {
        expired: { farms: 1, aiRequests: 50 },
        seed: { farms: 1, aiRequests: 50 },
        sprout: { farms: 3, aiRequests: 200 },
        harvest: { farms: 7, aiRequests: 500 },
        grove: { farms: 15, aiRequests: 1000 },
        summit: { farms: Infinity, aiRequests: Infinity }
      };

      const limit = resourceType === 'farm'
        ? limits[plan].farms
        : limits[plan].aiRequests;

      const current = resourceType === 'farm'
        ? usage.farmsCount
        : usage.aiRequestsThisMonth;

      const allowed = current < limit;

      setCanCreate(allowed);
      setReason(allowed ? null : `${plan} plan limit reached (${current}/${limit})`);
      setLoading(false);
    }

    checkUsage();
  }, [resourceType]);

  return { canCreate, loading, reason };
}

// Usage in component
function CreateFarmButton() {
  const { canCreate, loading, reason } = useUsageGuard('farm');

  if (loading) return <button disabled>Loading...</button>;

  return (
    <button
      onClick={handleCreateFarm}
      disabled={!canCreate}
      title={reason}
    >
      {canCreate ? 'Create Farm' : `Limit Reached - Upgrade to Create More`}
    </button>
  );
}

Get Subscription - GET current subscription plan
Create Checkout Session - POST to upgrade plan
Create Portal Session - POST to manage subscription
Get Invoices - GET payment history

​Endpoint

​Authentication

​Response

​Errors

​Usage Metrics Explained

​farmsCount

​aiRequestsThisMonth

​Plan Limits

​Seed Plan (€22/month)

​Sprout Plan (€49/month)

​Harvest Plan (€89/month) ⭐

​Grove Plan (€149/month)

​Summit Plan (€299+/month)

​Use Cases

​Check Usage Against Limits

​Show Usage Dashboard

​Check Before Creating Resource

​Monitor AI Request Usage

​Best Practices

​Integration Examples

​Usage Dashboard Card

​Usage Progress Bar

​Usage Guard Hook

​Related Endpoints

Endpoint

Authentication

Response

Errors

Usage Metrics Explained

farmsCount

aiRequestsThisMonth

Plan Limits

Seed Plan (€22/month)

Sprout Plan (€49/month)

Harvest Plan (€89/month) ⭐

Grove Plan (€149/month)

Summit Plan (€299+/month)

Use Cases

Check Usage Against Limits

Show Usage Dashboard

Check Before Creating Resource

Monitor AI Request Usage

Best Practices

Integration Examples

Usage Dashboard Card

Usage Progress Bar

Usage Guard Hook

Related Endpoints