Skip to main content

Adjustments, Gifts and Ad-hoc Charges

The Adjustments API is the main way to keep customer balances in sync with events that happen outside of Credyt. Whenever a payment, refund, or credit is processed externally, the platform is responsible for notifying Credyt so that wallet balances stay accurate.

Common use-cases​

  1. External PSP payments - when subscription or top-up payments are processed through your own payment provider, you add the balance in Credyt via an adjustment.
  2. Refunds - when funds are returned to a customer, you subtract the amount with a refund adjustment.
  3. Free credits / gifts - when you want to reward users, run promotions, or compensate for issues, you credit the customer's balance directly.
  4. Ad-hoc charges - when you may need to apply charges manually, outside of the normal usage processing flow.

External PSP Payments​

API Reference

When subscriptions or top-ups are charged through your own PSP, the payment never reaches Credyt directly. To maintain accurate balances, send an adjustment with the same amount and asset. A detailed implementation guide is available in our Hybrid model article.

Example​

This adjustment adds $25 to the customer’s USD account.

POST https://api.credyt.ai/customers/:customerId/wallet/adjustments
{
  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_name": "default",
  "asset": "USD",
  "amount": 25,
  "description": "Monthly Subscription",
  "reason": "external_topup",
  "expires_at": "2024-07-29T15:51:28.071Z",
  "metadata": {
    "psp": "stripe",
    "payment_intent": "pi_3RjbbNJNSIruR1rb0GwMGpH0"
  }
}

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-07-29T15:51:28.071Z"
}

Refunds​

API Reference

Refunds are negative adjustments. You refund through your PSP (or Stripe Dashboard if using Credyt payments), then notify Credyt. For further details, refer to our Refunds article.

Example​

This subtracts $20 from the customer’s fiat account balance (externally refunded).

POST https://api.credyt.ai/customers/:customerId/wallet/adjustments
{
  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_name": "default",
  "asset": "USD",
  "amount": -20,
  "description": "Technical failure",
  "reason": "external_refund",
  "expires_at": "2024-07-29T15:51:28.071Z",
  "metadata": {
    "psp": "stripe",
    "payment_intent": "pi_3RjbbNJNSIruR1rb0GwMGpH0"
  }
}

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-07-29T15:51:28.071Z"
}

Free Credits / Gifts​

API Reference

Credyt allows you to grant gifts or free credits to customers through the Adjustments API. This lets you reward users, run promotions, or compensate for issues with a simple API call that updates their wallet balance in real-time. You can also define an expiry date for these credits when granting them, enabling time-limited promotions and helping drive engagement, and monetization.

You can issue credits without a payment by applying a positive adjustment.

Example​

Customer wallet is credited with 1,000 tokens.

POST https://api.credyt.ai/customers/:customerId/wallet/adjustments
{
  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_name": "default",
  "asset": "TOKENS",
  "amount": 1000,
  "description": "Signup bonus",
  "reason": "gift",
  "expires_at": "2024-07-29T15:51:28.071Z",
  "metadata": {
    "signup_channel": "referral",
    "referral_id": "2c963f66afa6"
  }
}

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-07-29T15:51:28.071Z"
}

Ad-hoc Charges​

API Reference

While usage-based billing is typically driven by real-time events, there are situations where you may need to apply charges manually, outside of the normal usage processing flow. Use ad-hoc charge adjustments to do exactly that.

Ad-hoc charges are another form of balance adjustment, but unlike credits or gifts, they always deduct funds from a customer’s balance. This makes them particularly useful in scenarios where:

  • Usage data cannot be sent in real time due to technical issues or service interruptions
  • External data providers (for example, an AI API or third-party service) deliver usage information with delays
  • You need to apply one-off or corrective fees that aren’t tied to a usage event — such as overage adjustments, manual service fees, or administrative costs

Each charge includes details such as the amount, currency, description, and subject (a contextual reference, such as a session or service ID). You can also include optional metadata and store calculation inputs (e.g., volume, rate, or unit price) for traceability and transparency to the customer.

All ad-hoc charges appear in the customer’s Billing Portal usage history, displaying the information provided in the Create a charge request - including descriptions, amounts, and other contextual details you’ve shared.

To ensure safe retries, each request must include a unique transaction_id, which acts as an idempotency key. If the same transaction_id is sent again, Credyt will recognize it as a duplicate and will not duplicate the charge.

Example​

POST https://api.credyt.ai/customers/:customerId/wallet/charges
{
  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_name": "default",
  "asset": "USD",
  "subject": "chat_5f53d23a4958",
  "description": "Overage costs for GPT-4 usage",
  "metadata": {
    "model": "gpt-4-1"
  },
  "input_units": null,
  "input_volume": 2652000,
  "unit_price": null,
  "volume_rate": 0.5,
  "package_size": 1000000,
  "amount": 1.326
}

Key requirements and best practices​

  • A unique transaction_id is required for each adjustment.
  • Amounts should be positive for crediting the account (top-ups, subscriptions, gifts) and negative for debiting the account (refunds, other adjustments).
  • The reason field indicates the type of adjustment (external_topup, external_refund, gift, other).
  • The metadata field can be used to attach PSP references, campaign IDs, or internal notes for reconciliation.