orb-billing
Version:
The official TypeScript library for the Orb API
176 lines • 8.84 kB
JavaScript
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from "../../core/resource.mjs";
import * as BalanceTransactionsAPI from "./balance-transactions.mjs";
import { BalanceTransactions, } from "./balance-transactions.mjs";
import * as CostsAPI from "./costs.mjs";
import { Costs, } from "./costs.mjs";
import * as CreditsAPI from "./credits/credits.mjs";
import { Credits, } from "./credits/credits.mjs";
import { Page } from "../../core/pagination.mjs";
import { buildHeaders } from "../../internal/headers.mjs";
import { path } from "../../internal/utils/path.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(path `/customers/${customerID}`, { body, ...options });
}
/**
* This endpoint returns a list of all customers for an account. The list of
* customers is ordered starting from the most recently created customer. This
* endpoint follows Orb's
* [standardized pagination format](/api-reference/pagination).
*
* See [Customer](/core-concepts##customer) for an overview of the customer model.
*/
list(query = {}, options) {
return this._client.getAPIList('/customers', (Page), { 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(path `/customers/${customerID}`, {
...options,
headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
});
}
/**
* Creates a portal session for the customer, returning a short-lived URL that
* provides authenticated access to the customer's billing portal. The session
* expires after `expires_in_minutes` (default 60, max 180). By default, creating a
* new session invalidates any other active portal sessions for the customer; pass
* `invalidate_existing=false` to allow concurrent sessions.
*/
createPortalSession(customerID, body, options) {
return this._client.post(path `/customers/${customerID}/portal_sessions`, { body, ...options });
}
/**
* Creates a portal session for the customer, returning a short-lived URL that
* provides authenticated access to the customer's billing portal. The session
* expires after `expires_in_minutes` (default 60, max 180). By default, creating a
* new session invalidates any other active portal sessions for the customer; pass
* `invalidate_existing=false` to allow concurrent sessions.
*/
createPortalSessionByExternalID(externalCustomerID, body, options) {
return this._client.post(path `/customers/external_customer_id/${externalCustomerID}/portal_sessions`, {
body,
...options,
});
}
/**
* 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(path `/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(path `/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(path `/customers/${customerID}/sync_payment_methods_from_gateway`, {
...options,
headers: buildHeaders([{ 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(path `/customers/external_customer_id/${externalCustomerID}/sync_payment_methods_from_gateway`, { ...options, headers: buildHeaders([{ 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(path `/customers/external_customer_id/${id}`, { body, ...options });
}
}
Customers.Costs = Costs;
Customers.Credits = Credits;
Customers.BalanceTransactions = BalanceTransactions;
//# sourceMappingURL=customers.mjs.map