# 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[​](#common-use-cases "Direct link to 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[​](#external-psp-payments "Direct link to External PSP Payments")

[API Reference](https://docs.credyt.ai/api/customer-wallet-ops-create-adjustment.md)

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](https://docs.credyt.ai/use-cases/hybrid-model.md) article.

### Example[​](#example "Direct link to Example")

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

* REST API
* TypeScript SDK
* Python SDK

POST https\://api.credyt.ai/customers/cust\_473cr1y0ghbyc3m1yfbwvn3nxx/wallet/adjustments

```json
{
  "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**

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

```

```typescript
await client.customerWalletOps.createAdjustment("cust_473cr1y0ghbyc3m1yfbwvn3nxx", {
  transactionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  accountName: "default",
  asset: "USD",
  amount: 25,
  description: "Monthly Subscription",
  reason: "external_topup",
  expiresAt: "2024-07-29T15:51:28.071Z",
  metadata: {
    psp: "stripe",
    paymentIntent: "pi_3RjbbNJNSIruR1rb0GwMGpH0",
  },
});

```

[View full sample on GitHub](https://github.com/credyt/sdk-ts/blob/main/samples/walletsCustomerWalletOpsCreateAdjustmentSample.ts#L56)

**SDK response object**

```typescript
const response = {
  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  createdAt: "2024-07-29T15:51:28.071Z",
};

```

```python
response = client.customer_wallet_ops.create_adjustment(
    customer_id="cust_473cr1y0ghbyc3m1yfbwvn3nxx",
    body={
    "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",
    },
  },
)

```

**SDK response object**

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

```

## Refunds[​](#refunds "Direct link to Refunds")

[API Reference](https://docs.credyt.ai/api/customer-wallet-ops-create-adjustment.md)

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](https://docs.credyt.ai/advanced-topics/refunds.md).

### Example[​](#example-1 "Direct link to Example")

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

* REST API
* TypeScript SDK
* Python SDK

POST https\://api.credyt.ai/customers/cust\_473cr1y0ghbyc3m1yfbwvn3nxx/wallet/adjustments

```json
{
  "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"
}

```

**Response**

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

```

```typescript
await client.customerWalletOps.createAdjustment("cust_473cr1y0ghbyc3m1yfbwvn3nxx", {
  transactionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  accountName: "default",
  asset: "USD",
  amount: -20,
  description: "Technical failure",
  reason: "external_refund",
  expiresAt: "2024-07-29T15:51:28.071Z",
});

```

[View full sample on GitHub](https://github.com/credyt/sdk-ts/blob/main/samples/walletsCustomerWalletOpsCreateAdjustmentSample.ts#L158)

**SDK response object**

```typescript
const response = {
  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  createdAt: "2024-07-29T15:51:28.071Z",
};

```

```python
response = client.customer_wallet_ops.create_adjustment(
    customer_id="cust_473cr1y0ghbyc3m1yfbwvn3nxx",
    body={
    "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",
  },
)

```

**SDK response object**

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

```

## Free Credits / Gifts[​](#free-credits--gifts "Direct link to Free Credits / Gifts")

[API Reference](https://docs.credyt.ai/api/customer-wallet-ops-create-adjustment.md)

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[​](#example-2 "Direct link to Example")

Customer wallet is credited with 1,000 tokens.

* REST API
* TypeScript SDK
* Python SDK

POST https\://api.credyt.ai/customers/cust\_473cr1y0ghbyc3m1yfbwvn3nxx/wallet/adjustments

```json
{
  "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**

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

```

```typescript
await client.customerWalletOps.createAdjustment("cust_473cr1y0ghbyc3m1yfbwvn3nxx", {
  transactionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  accountName: "default",
  asset: "TOKENS",
  amount: 1000,
  description: "Signup bonus",
  reason: "gift",
  expiresAt: "2024-07-29T15:51:28.071Z",
  metadata: {
    signupChannel: "referral",
    referralId: "2c963f66afa6",
  },
});

```

[View full sample on GitHub](https://github.com/credyt/sdk-ts/blob/main/samples/walletsCustomerWalletOpsCreateAdjustmentSample.ts#L193)

**SDK response object**

```typescript
const response = {
  id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  createdAt: "2024-07-29T15:51:28.071Z",
};

```

```python
response = client.customer_wallet_ops.create_adjustment(
    customer_id="cust_473cr1y0ghbyc3m1yfbwvn3nxx",
    body={
    "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",
    },
  },
)

```

**SDK response object**

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

```

## Ad-hoc Charges[​](#ad-hoc-charges "Direct link to Ad-hoc Charges")

[API Reference](https://docs.credyt.ai/api/customer-wallet-ops-create-charge.md)

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[​](#example-3 "Direct link to Example")

* REST API
* TypeScript SDK
* Python SDK

POST https\://api.credyt.ai/customers/cust\_473cr1y0ghbyc3m1yfbwvn3nxx/wallet/charges

```json
{
  "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
}

```

```typescript
await client.customerWalletOps.createCharge("cust_473cr1y0ghbyc3m1yfbwvn3nxx", {
  transactionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  accountName: "default",
  asset: "USD",
  subject: "chat_5f53d23a4958",
  description: "Overage costs for GPT-4 usage",
  metadata: {
    model: "gpt-4-1",
  },
  inputUnits: null,
  inputVolume: 2652000,
  unitPrice: null,
  volumeRate: 0.5,
  packageSize: 1000000,
  amount: 1.326,
});

```

[View full sample on GitHub](https://github.com/credyt/sdk-ts/blob/main/samples/walletsCustomerWalletOpsCreateChargeSample.ts#L15)

```python
response = client.customer_wallet_ops.create_charge(
    customer_id="cust_473cr1y0ghbyc3m1yfbwvn3nxx",
    body={
    "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": None,
    "input_volume": 2652000,
    "unit_price": None,
    "volume_rate": 0.5,
    "package_size": 1000000,
    "amount": 1.326,
  },
)

```

## Key requirements and best practices[​](#key-requirements-and-best-practices "Direct link to 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.