Credits

curl -X GET "https://api.talkturo.com/api/credits?accountId=8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z"

const response = await fetch(
  "https://api.talkturo.com/api/credits?accountId=8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z",
    },
  }
);

const data = await response.json();
console.log(data);

{
  "success": true,
  "credits": {
    "id": "c8b74c77-8f54-4f72-bfc6-2dc0db7d6f0b",
    "account_id": "8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
    "credits": 18420,
    "total_purchased": 25000,
    "total_used": 6580,
    "auto_reload_enabled": true,
    "auto_reload_threshold": 5000,
    "auto_reload_amount_usd": 199
  }
}

curl -X POST "https://api.talkturo.com/api/credits" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
    "amount": 320,
    "description": "Outbound call usage for campaign cmp_7d2fa19c",
    "metadata": {
      "assistantId": "0b760e0d-4b10-4ee8-9c8b-89f02d0a9149",
      "campaignId": "cmp_7d2fa19c",
      "minutes": 4.8
    }
  }'

const response = await fetch("https://api.talkturo.com/api/credits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z",
  },
  body: JSON.stringify({
    accountId: "8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
    amount: 320,
    description: "Outbound call usage for campaign cmp_7d2fa19c",
    metadata: {
      assistantId: "0b760e0d-4b10-4ee8-9c8b-89f02d0a9149",
      campaignId: "cmp_7d2fa19c",
      minutes: 4.8,
    },
  }),
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "transactionId": "txn_credits_4aa92d1f6d10",
  "balance": 18100,
  "autoReloadTriggered": false
}

{
  "success": false,
  "error": "Insufficient credits"
}

curl -X POST "https://api.talkturo.com/api/credits/checkout" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
    "accountSlug": "acme-sales",
    "planId": "credits_growth_500"
  }'

const response = await fetch("https://api.talkturo.com/api/credits/checkout", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer tk_live_example_9xmk7q2r5s8d4m1n6p3v7y2z",
  },
  body: JSON.stringify({
    accountId: "8f6b7a40-8f86-4cfd-a7ec-0b0b52f5c8d2",
    accountSlug: "acme-sales",
    planId: "credits_growth_500",
  }),
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "checkoutToken": "seti_example_4c0f6b0a2a594f0b8f5d1e5d",
  "sessionId": "cs_test_b1b8ac39f2f54ceaa55d4e9b2f13",
  "credits": 50000,
  "amount": 499
}

Credits endpoints

Use the credits API to read an account balance, record usage deductions, and start credit purchases through Stripe. The balance, deduction, and checkout endpoints support dual authentication, while account management endpoints for auto-reload and history use session authentication.

Endpoint summary

Get credits balance

Read the current balance for an account with GET /api/credits. If you omit accountId, the API uses the authenticated account from the request context.

Query parameters

Response fields

Deduct credits

Record usage and decrement an account balance with POST /api/credits. This endpoint calls the deduct_credits() database function and returns the updated balance.

Body parameters

Response fields

Auto-reload behavior after a deduction

If auto-reload is enabled and the remaining balance drops below auto_reload_threshold, the API attempts to trigger a reload after the deduction succeeds. The deduction response still returns immediately with autoReloadTriggered so your application can decide whether to notify the account owner or pause high-cost actions until the balance refreshes.

Create a checkout session

Start a credit purchase with POST /api/credits/checkout. Use either a predefined planId or a custom purchase amount and credit quantity.

Body parameters

Response fields

Purchase rules

• Provide planId, or provide both customAmount and customCredits.
• Custom purchases must have a minimum customAmount of 99.
• The endpoint creates an embedded Stripe Checkout session and returns a client secret in checkoutToken.

Session-authenticated credits endpoints

Use the following endpoints from a signed-in browser session when you need account-level credits management and history screens.

Get or update auto-reload

GET /api/credits/auto-reload reads the current auto-reload settings. POST /api/credits/auto-reload updates those settings for the signed-in account.

Claim pending grants

POST /api/credits/claim-grants applies any pending credit grants to the signed-in account. Use this endpoint after account actions that provision promotional or manual credits.

List available plans

GET /api/credits/plans returns the purchase plans available to the signed-in account. Use it to populate a billing UI before calling checkout.

Get statement history

GET /api/credits/statement returns statement-style credit history for the signed-in account. Use it when you need a chronological ledger view.

Get transaction history

GET /api/credits/transactions returns transaction-level credit history for the signed-in account. Use it when you need detailed usage and purchase records.

Common integration patterns

Developers usually combine these endpoints in a short billing loop:

• Read the current balance before starting a high-cost action.
• Deduct credits when usage is confirmed.
• Handle HTTP 402 by pausing work and prompting for a purchase flow.
• Create a checkout session when the user needs to buy more credits.
• Refresh the balance after purchase completion or auto-reload.

Related billing flow

Credits deductions and checkout creation cover the API side of usage billing. The actual credit grant happens after payment succeeds through Stripe webhook processing, so a successful checkout session does not change the balance until payment completion is recorded.