orb-billing/resources/customers/balance-transactions.js

The official TypeScript library for the Orb API

"use strict";
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
Object.defineProperty(exports, "__esModule", { value: true });
exports.BalanceTransactions = void 0;
const resource_1 = require("../../core/resource.js");
const pagination_1 = require("../../core/pagination.js");
const path_1 = require("../../internal/utils/path.js");
/**
 * A customer is a buyer of your products, and the other party to the billing relationship.
 *
 * In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these
 * match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an
 * `external_customer_id` with your own identifier. See
 * [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these
 * aliases work in Orb.
 *
 * In addition to having an identifier in your system, a customer may exist in a payment provider solution like
 * Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping.
 *
 * A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which
 * defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for
 * information on what this timezone parameter influences within Orb.
 */
class BalanceTransactions extends resource_1.APIResource {
    /**
     * Creates an immutable balance transaction that updates the customer's balance and
     * returns back the newly created transaction.
     */
    create(customerID, body, options) {
        return this._client.post((0, path_1.path) `/customers/${customerID}/balance_transactions`, { body, ...options });
    }
    /**
     * ## The customer balance
     *
     * The customer balance is an amount in the customer's currency, which Orb
     * automatically applies to subsequent invoices. This balance can be adjusted
     * manually via Orb's webapp on the customer details page. You can use this balance
     * to provide a fixed mid-period credit to the customer. Commonly, this is done due
     * to system downtime/SLA violation, or an adhoc adjustment discussed with the
     * customer.
     *
     * If the balance is a positive value at the time of invoicing, it represents that
     * the customer has credit that should be used to offset the amount due on the next
     * issued invoice. In this case, Orb will automatically reduce the next invoice by
     * the balance amount, and roll over any remaining balance if the invoice is fully
     * discounted.
     *
     * If the balance is a negative value at the time of invoicing, Orb will increase
     * the invoice's amount due with a positive adjustment, and reset the balance to 0.
     *
     * This endpoint retrieves all customer balance transactions in reverse
     * chronological order for a single customer, providing a complete audit trail of
     * all adjustments and invoice applications.
     */
    list(customerID, query = {}, options) {
        return this._client.getAPIList((0, path_1.path) `/customers/${customerID}/balance_transactions`, (pagination_1.Page), { query, ...options });
    }
}
exports.BalanceTransactions = BalanceTransactions;
//# sourceMappingURL=balance-transactions.js.map