orb-billing/resources/subscription-changes.d.ts

The official TypeScript library for the Orb API

import { APIResource } from "../resource.js";
import * as Core from "../core.js";
import * as Shared from "./shared.js";
import * as CustomersAPI from "./customers/customers.js";
import * as PlansAPI from "./plans/plans.js";
export declare class SubscriptionChanges extends APIResource {
    /**
     * This endpoint returns a subscription change given an identifier.
     *
     * A subscription change is created by including
     * `Create-Pending-Subscription-Change: True` in the header of a subscription
     * mutation API call (e.g.
     * [create subscription endpoint](/api-reference/subscription/create-subscription),
     * [schedule plan change endpoint](/api-reference/subscription/schedule-plan-change),
     * ...). The subscription change will be referenced by the
     * `pending_subscription_change` field in the response.
     */
    retrieve(subscriptionChangeId: string, options?: Core.RequestOptions): Core.APIPromise<SubscriptionChangeRetrieveResponse>;
    /**
     * Apply a subscription change to perform the intended action. If a positive amount
     * is passed with a request to this endpoint, any eligible invoices that were
     * created will be issued immediately if they only contain in-advance fees.
     */
    apply(subscriptionChangeId: string, body?: SubscriptionChangeApplyParams, options?: Core.RequestOptions): Core.APIPromise<SubscriptionChangeApplyResponse>;
    apply(subscriptionChangeId: string, options?: Core.RequestOptions): Core.APIPromise<SubscriptionChangeApplyResponse>;
    /**
     * Cancel a subscription change. The change can no longer be applied. A
     * subscription can only have one "pending" change at a time - use this endpoint to
     * cancel an existing change before creating a new one.
     */
    cancel(subscriptionChangeId: string, options?: Core.RequestOptions): Core.APIPromise<SubscriptionChangeCancelResponse>;
}
export interface MutatedSubscription {
    id: string;
    /**
     * The current plan phase that is active, only if the subscription's plan has
     * phases.
     */
    active_plan_phase_order: number | null;
    /**
     * The adjustment intervals for this subscription sorted by the start_date of the
     * adjustment interval.
     */
    adjustment_intervals: Array<Shared.AdjustmentInterval>;
    /**
     * Determines whether issued invoices for this subscription will automatically be
     * charged with the saved payment method on the due date. This property defaults to
     * the plan's behavior. If null, defaults to the customer's setting.
     */
    auto_collection: boolean | null;
    billing_cycle_anchor_configuration: Shared.BillingCycleAnchorConfiguration;
    /**
     * The day of the month on which the billing cycle is anchored. If the maximum
     * number of days in a month is greater than this value, the last day of the month
     * is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing
     * period begins on the 30th.
     */
    billing_cycle_day: number;
    created_at: string;
    /**
     * The end of the current billing period. This is an exclusive timestamp, such that
     * the instant returned is not part of the billing period. Set to null for
     * subscriptions that are not currently active.
     */
    current_billing_period_end_date: string | null;
    /**
     * The start date of the current billing period. This is an inclusive timestamp;
     * the instant returned is exactly the beginning of the billing period. Set to null
     * if the subscription is not currently active.
     */
    current_billing_period_start_date: string | null;
    /**
     * 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.
     */
    customer: CustomersAPI.Customer;
    /**
     * Determines the default memo on this subscriptions' invoices. Note that if this
     * is not provided, it is determined by the plan configuration.
     */
    default_invoice_memo: string | null;
    /**
     * @deprecated The discount intervals for this subscription sorted by the
     * start_date. This field is deprecated in favor of `adjustment_intervals`.
     */
    discount_intervals: Array<Shared.AmountDiscountInterval | Shared.PercentageDiscountInterval | Shared.UsageDiscountInterval>;
    /**
     * The date Orb stops billing for this subscription.
     */
    end_date: string | null;
    fixed_fee_quantity_schedule: Array<Shared.FixedFeeQuantityScheduleEntry>;
    invoicing_threshold: string | null;
    /**
     * @deprecated The maximum intervals for this subscription sorted by the
     * start_date. This field is deprecated in favor of `adjustment_intervals`.
     */
    maximum_intervals: Array<Shared.MaximumInterval>;
    /**
     * User specified key-value pairs for the resource. If not present, this defaults
     * to an empty dictionary. Individual keys can be removed by setting the value to
     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
     * `null`.
     */
    metadata: {
        [key: string]: string;
    };
    /**
     * @deprecated The minimum intervals for this subscription sorted by the
     * start_date. This field is deprecated in favor of `adjustment_intervals`.
     */
    minimum_intervals: Array<Shared.MinimumInterval>;
    /**
     * The name of the subscription.
     */
    name: string;
    /**
     * Determines the difference between the invoice issue date for subscription
     * invoices as the date that they are due. A value of `0` here represents that the
     * invoice is due on issue, whereas a value of `30` represents that the customer
     * has a month to pay the invoice.
     */
    net_terms: number;
    /**
     * A pending subscription change if one exists on this subscription.
     */
    pending_subscription_change: Shared.SubscriptionChangeMinified | null;
    /**
     * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
     * subscribed to by a customer. Plans define the billing behavior of the
     * subscription. You can see more about how to configure prices in the
     * [Price resource](/reference/price).
     */
    plan: PlansAPI.Plan | null;
    /**
     * The price intervals for this subscription.
     */
    price_intervals: Array<Shared.PriceInterval>;
    redeemed_coupon: Shared.CouponRedemption | null;
    /**
     * The date Orb starts billing for this subscription.
     */
    start_date: string;
    status: 'active' | 'ended' | 'upcoming';
    trial_info: Shared.SubscriptionTrialInfo;
    /**
     * The resources that were changed as part of this operation. Only present when
     * fetched through the subscription changes API or if the
     * `include_changed_resources` parameter was passed in the request.
     */
    changed_resources?: Shared.ChangedSubscriptionResources | null;
}
/**
 * A subscription change represents a desired new subscription / pending change to
 * an existing subscription. It is a way to first preview the effects on the
 * subscription as well as any changes/creation of invoices (see
 * `subscription.changed_resources`).
 */
export interface SubscriptionChangeRetrieveResponse {
    id: string;
    /**
     * Subscription change will be cancelled at this time and can no longer be applied.
     */
    expiration_time: string;
    status: 'pending' | 'applied' | 'cancelled';
    subscription: MutatedSubscription | null;
    /**
     * When this change was applied.
     */
    applied_at?: string | null;
    /**
     * When this change was cancelled.
     */
    cancelled_at?: string | null;
}
/**
 * A subscription change represents a desired new subscription / pending change to
 * an existing subscription. It is a way to first preview the effects on the
 * subscription as well as any changes/creation of invoices (see
 * `subscription.changed_resources`).
 */
export interface SubscriptionChangeApplyResponse {
    id: string;
    /**
     * Subscription change will be cancelled at this time and can no longer be applied.
     */
    expiration_time: string;
    status: 'pending' | 'applied' | 'cancelled';
    subscription: MutatedSubscription | null;
    /**
     * When this change was applied.
     */
    applied_at?: string | null;
    /**
     * When this change was cancelled.
     */
    cancelled_at?: string | null;
}
/**
 * A subscription change represents a desired new subscription / pending change to
 * an existing subscription. It is a way to first preview the effects on the
 * subscription as well as any changes/creation of invoices (see
 * `subscription.changed_resources`).
 */
export interface SubscriptionChangeCancelResponse {
    id: string;
    /**
     * Subscription change will be cancelled at this time and can no longer be applied.
     */
    expiration_time: string;
    status: 'pending' | 'applied' | 'cancelled';
    subscription: MutatedSubscription | null;
    /**
     * When this change was applied.
     */
    applied_at?: string | null;
    /**
     * When this change was cancelled.
     */
    cancelled_at?: string | null;
}
export interface SubscriptionChangeApplyParams {
    /**
     * Description to apply to the balance transaction representing this credit.
     */
    description?: string | null;
    /**
     * Mark all pending invoices that are payable as paid. If amount is also provided,
     * mark as paid and credit the difference to the customer's balance.
     */
    mark_as_paid?: boolean | null;
    /**
     * An optional external ID to associate with the payment. Only applicable when
     * mark_as_paid is true.
     */
    payment_external_id?: string | null;
    /**
     * Optional notes about the payment. Only applicable when mark_as_paid is true.
     */
    payment_notes?: string | null;
    /**
     * A date string to specify the date the payment was received. Only applicable when
     * mark_as_paid is true. If not provided, defaults to the current date.
     */
    payment_received_date?: string | null;
    /**
     * Amount already collected to apply to the customer's balance. If mark_as_paid is
     * also provided, credit the difference to the customer's balance.
     */
    previously_collected_amount?: string | null;
}
export declare namespace SubscriptionChanges {
    export { type MutatedSubscription as MutatedSubscription, type SubscriptionChangeRetrieveResponse as SubscriptionChangeRetrieveResponse, type SubscriptionChangeApplyResponse as SubscriptionChangeApplyResponse, type SubscriptionChangeCancelResponse as SubscriptionChangeCancelResponse, type SubscriptionChangeApplyParams as SubscriptionChangeApplyParams, };
}
//# sourceMappingURL=subscription-changes.d.ts.map