orb-billing
Version:
The official TypeScript library for the Orb API
153 lines • 7.58 kB
JavaScript
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from "../../resource.mjs";
import { isRequestOptions } from "../../core.mjs";
import * as BalanceTransactionsAPI from "./balance-transactions.mjs";
import { BalanceTransactionListResponsesPage, BalanceTransactions, } from "./balance-transactions.mjs";
import * as CostsAPI from "./costs.mjs";
import { Costs, } from "./costs.mjs";
import * as CreditsAPI from "./credits/credits.mjs";
import { CreditListByExternalIDResponsesPage, CreditListResponsesPage, Credits, } from "./credits/credits.mjs";
import { Page } from "../../pagination.mjs";
/**
* 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.
*/
export class Customers extends APIResource {
constructor() {
super(...arguments);
this.costs = new CostsAPI.Costs(this._client);
this.credits = new CreditsAPI.Credits(this._client);
this.balanceTransactions = new BalanceTransactionsAPI.BalanceTransactions(this._client);
}
/**
* This operation is used to create an Orb customer, who is party to the core
* billing relationship. See [Customer](/core-concepts##customer) for an overview
* of the customer resource.
*
* This endpoint is critical in the following Orb functionality:
*
* - Automated charges can be configured by setting `payment_provider` and
* `payment_provider_id` to automatically issue invoices
* - [Customer ID Aliases](/events-and-metrics/customer-aliases) can be configured
* by setting `external_customer_id`
* - [Timezone localization](/essentials/timezones) can be configured on a
* per-customer basis by setting the `timezone` parameter
*/
create(body, options) {
return this._client.post('/customers', { body, ...options });
}
/**
* This endpoint can be used to update the `payment_provider`,
* `payment_provider_id`, `name`, `email`, `email_delivery`, `tax_id`,
* `auto_collection`, `metadata`, `shipping_address`, `billing_address`,
* `additional_emails`, and `currency` of an existing customer. `currency` can only
* be set if it has not already been set on the customer. Other fields on a
* customer are currently immutable.
*/
update(customerId, body, options) {
return this._client.put(`/customers/${customerId}`, { body, ...options });
}
list(query = {}, options) {
if (isRequestOptions(query)) {
return this.list({}, query);
}
return this._client.getAPIList('/customers', CustomersPage, { query, ...options });
}
/**
* This performs a deletion of this customer, its subscriptions, and its invoices,
* provided the customer does not have any issued invoices. Customers with issued
* invoices cannot be deleted. This operation is irreversible. Note that this is a
* _soft_ deletion, but the data will be inaccessible through the API and Orb
* dashboard.
*
* For a hard-deletion, please reach out to the Orb team directly.
*
* **Note**: This operation happens asynchronously and can be expected to take a
* few minutes to propagate to related resources. However, querying for the
* customer on subsequent GET requests while deletion is in process will reflect
* its deletion.
*/
delete(customerId, options) {
return this._client.delete(`/customers/${customerId}`, {
...options,
headers: { Accept: '*/*', ...options?.headers },
});
}
/**
* This endpoint is used to fetch customer details given an identifier. If the
* `Customer` is in the process of being deleted, only the properties `id` and
* `deleted: true` will be returned.
*
* See the [Customer resource](/core-concepts#customer) for a full discussion of
* the Customer model.
*/
fetch(customerId, options) {
return this._client.get(`/customers/${customerId}`, options);
}
/**
* This endpoint is used to fetch customer details given an `external_customer_id`
* (see [Customer ID Aliases](/events-and-metrics/customer-aliases)).
*
* Note that the resource and semantics of this endpoint exactly mirror
* [Get Customer](fetch-customer).
*/
fetchByExternalId(externalCustomerId, options) {
return this._client.get(`/customers/external_customer_id/${externalCustomerId}`, options);
}
/**
* Sync Orb's payment methods for the customer with their gateway.
*
* This method can be called before taking an action that may cause the customer to
* be charged, ensuring that the most up-to-date payment method is charged.
*
* **Note**: This functionality is currently only available for Stripe.
*/
syncPaymentMethodsFromGateway(customerId, options) {
return this._client.post(`/customers/${customerId}/sync_payment_methods_from_gateway`, {
...options,
headers: { Accept: '*/*', ...options?.headers },
});
}
/**
* Sync Orb's payment methods for the customer with their gateway.
*
* This method can be called before taking an action that may cause the customer to
* be charged, ensuring that the most up-to-date payment method is charged.
*
* **Note**: This functionality is currently only available for Stripe.
*/
syncPaymentMethodsFromGatewayByExternalCustomerId(externalCustomerId, options) {
return this._client.post(`/customers/external_customer_id/${externalCustomerId}/sync_payment_methods_from_gateway`, { ...options, headers: { Accept: '*/*', ...options?.headers } });
}
/**
* This endpoint is used to update customer details given an `external_customer_id`
* (see [Customer ID Aliases](/events-and-metrics/customer-aliases)). Note that the
* resource and semantics of this endpoint exactly mirror
* [Update Customer](update-customer).
*/
updateByExternalId(id, body, options) {
return this._client.put(`/customers/external_customer_id/${id}`, { body, ...options });
}
}
export class CustomersPage extends Page {
}
Customers.CustomersPage = CustomersPage;
Customers.Costs = Costs;
Customers.Credits = Credits;
Customers.CreditListResponsesPage = CreditListResponsesPage;
Customers.CreditListByExternalIDResponsesPage = CreditListByExternalIDResponsesPage;
Customers.BalanceTransactions = BalanceTransactions;
Customers.BalanceTransactionListResponsesPage = BalanceTransactionListResponsesPage;
//# sourceMappingURL=customers.mjs.map