Skip to content

CreditBalance ​

Type: schema

Description ​

A change of a customer's credit balance (bank-transfer money received but not yet used), with the balances after it.

TypeScript Definition ​

typescript
CreditBalance: {{
            /**
             * @description Direction of the change: `credit` adds to the balance, `debit` uses it.
             * @enum {string}
             */
            transaction_type: "credit" | "debit";
            /** @description How much the balance moved. */
            amount: number;
            /**
             * @description What moved it: a deposit attributed to the customer or recorded for them by an admin (`deposit-attributed`), a settlement against their orders (`order-settlement`), a reversed settlement (`settlement-reversal`), a payout of the credit to their bank account (`balance-refund`): reserved (`debit`), or released when it failed or was cancelled (`credit`), or a hold on their money for an admin's review (`hold`): placed (`debit`; `credit` when it holds a deposit already below zero) or released (the reverse). Money held for review moves the balance only through its hold.
             * @enum {string}
             */
            reason: "deposit-attributed" | "order-settlement" | "settlement-reversal" | "balance-refund" | "hold";
            /** @description The payment records (`payment_id`) whose money moved; for a hold, the deposits it holds. */
            payment_ids: string[];
            /** @description The orders settled, whose settlement was reversed, or whose refund the payout is; empty for an attribution, a payout of the balance itself, or a hold. */
            order_numbers: string[];
            /** @description Total bank-transfer money received from the customer. */
            received_amount: number;
            /** @description Part of `received_amount` not in the balance: settled against orders, refunded, reserved by a credit-balance refund in progress, or held for an admin's review. */
            settled_amount: number;
            /** @description The credit balance after the change: `received_amount` minus `settled_amount`. Below `0` when more was refunded than was left. */
            balance_amount: number;
        };
        /**
         * CreditBalanceRefund
         * @description A refund of a customer's unused bank-transfer credit to their bank account, as the `credit_balance.refund.*` events carry it: the fields of an order refund, with its own statuses.
         */
}

OpenAPI Schema ​

json
{
  "title": "CreditBalance",
  "description": "A change of a customer's credit balance (bank-transfer money received but not yet used), with the balances after it.",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/CreditBalance",
    "description": "API reference for the CreditBalance schema"
  },
  "required": [
    "amount",
    "balance_amount",
    "order_numbers",
    "payment_ids",
    "reason",
    "received_amount",
    "settled_amount",
    "transaction_type"
  ],
  "properties": {
    "transaction_type": {
      "description": "Direction of the change: `credit` adds to the balance, `debit` uses it.",
      "type": "string",
      "enum": [
        "credit",
        "debit"
      ]
    },
    "amount": {
      "description": "How much the balance moved.",
      "type": "number"
    },
    "reason": {
      "description": "What moved it: a deposit attributed to the customer or recorded for them by an admin (`deposit-attributed`), a settlement against their orders (`order-settlement`), a reversed settlement (`settlement-reversal`), a payout of the credit to their bank account (`balance-refund`): reserved (`debit`), or released when it failed or was cancelled (`credit`), or a hold on their money for an admin's review (`hold`): placed (`debit`; `credit` when it holds a deposit already below zero) or released (the reverse). Money held for review moves the balance only through its hold.",
      "type": "string",
      "enum": [
        "deposit-attributed",
        "order-settlement",
        "settlement-reversal",
        "balance-refund",
        "hold"
      ]
    },
    "payment_ids": {
      "description": "The payment records (`payment_id`) whose money moved; for a hold, the deposits it holds.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "order_numbers": {
      "description": "The orders settled, whose settlement was reversed, or whose refund the payout is; empty for an attribution, a payout of the balance itself, or a hold.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "received_amount": {
      "description": "Total bank-transfer money received from the customer.",
      "type": "number"
    },
    "settled_amount": {
      "description": "Part of `received_amount` not in the balance: settled against orders, refunded, reserved by a credit-balance refund in progress, or held for an admin's review.",
      "type": "number"
    },
    "balance_amount": {
      "description": "The credit balance after the change: `received_amount` minus `settled_amount`. Below `0` when more was refunded than was left.",
      "type": "number"
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: