declarations
Version:
[](https://www.npmjs.com/package/declarations)
1,310 lines (1,102 loc) • 322 kB
TypeScript
// Type definitions for stripe-node 4.6.0
// Project: https://github.com/stripe/stripe-node/
// Definitions by: William Johnston <https://github.com/wjohnsto>, Peter Harris <https://github.com/codeanimal/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
/// <reference path="../bluebird/bluebird-2.0.d.ts" />
/// <reference path="../node/node.d.ts" />
declare module 'stripe' {
var out: StripeNode.StripeExport;
export = out;
}
declare namespace StripeNode {
interface StripeExport extends StripeStatic {
new (apiKey: string, version?: string): Stripe;
(apiKey: string, version?: string): Stripe;
}
interface StripeStatic {
DEFAULT_HOST: string;
DEFAULT_PORT: string;
DEFAULT_BASE_PATH: string;
DEFAULT_API_VERSION: string;
DEFAULT_TIMEOUT: number;
PACKAGE_VERSION: string;
USER_AGENT: {
bindings_version: string;
lang: string;
lang_version: string;
platform: string;
publisher: string;
uname: string;
};
USER_AGENT_SERIALIZED: string;
resources: typeof resources;
StripeResource: typeof StripeResource;
}
// Helper
type IBankAccount = bankAccounts.IBankAccount;
type ICard = cards.ICard;
interface Stripe extends StripeStatic {
accounts: resources.Accounts;
balance: resources.Balance;
charges: resources.Charges;
coupons: resources.Coupons;
customers: resources.Customers;
disputes: resources.Disputes;
events: resources.Events;
invoices: resources.Invoices;
invoiceItems: resources.InvoiceItems;
plans: resources.Plans;
/**
* @deprecated
*/
recipientCards: resources.RecipientCards;
/**
* @deprecated
*/
recipients: resources.Recipients;
subscriptions: resources.Subscriptions;
tokens: resources.Tokens;
transfers: resources.Transfers;
applicationFees: resources.ApplicationFees;
fileUploads: resources.FileUploads;
bitcoinReceivers: resources.BitcoinReceivers;
refunds: resources.Refunds;
countrySpecs: resources.CountrySpecs;
orders: resources.Orders;
products: resources.Products;
skus: resources.SKUs;
setHost(host: string): void;
setHost(host: string, port: string|number): void;
setHost(host: string, port: string|number, protocol: string): void;
setProtocol(protocol: string): void;
setPort(port: string|number): void;
setApiVersion(version?: string): void;
setApiKey(key?: string): void;
setTimeout(timeout?: number): void;
setHttpAgent(agent: string): void;
getConstant(c: string): any;
getClientUserAgent(response: (userAgent: string) => void): void;
}
namespace accounts {
interface IAccount extends IResourceObject, IAccountShared {
/**
* Value is "account"
*/
object: string;
/**
* Whether or not the account can create live charges
*/
charges_enabled: boolean;
/**
* The country of the account
*/
country: string;
/**
* Whether or not account details have been submitted yet. Standalone
* accounts cannot receive transfers before this is true.
*/
details_submitted: boolean;
/**
* The display name for this account. This is used on the Stripe dashboard to
* help you differentiate between accounts.
*/
display_name: string;
/**
* Whether or not Stripe will send automatic transfers for this account. This
* is only false when Stripe is waiting for additional information from the
* account holder.
*/
transfers_enabled: boolean;
/**
* The state of the account’s information requests, including what
* information is needed and by when it must be provided.
*/
verification: {
/**
* A string describing the reason for this account being unable to charge
* and/or transfer, if that is the case. Possible values are "rejected.fraud",
* "rejected.terms_of_service", "rejected.listed", "rejected.other",
* "fields_needed", "listed", or "other".
*/
disabled_reason: string;
/**
* At what time the fields_needed must be provided. If this date is in
* the past, the account is already in bad standing, and providing
* fields_needed is necessary to re-enable transfers and prevent other
* consequences. If this date is in the future, fields_needed must be
* provided to ensure the account remains in good standing.
*/
due_by: number;
/**
* Field names that need to be provided for the account to remain in good
* standing. Nested fields are separated by "." (for example,
* "legal_entity.first_name").
*/
fields_needed: Array<string>;
}
}
interface IAccountCreationOptions extends IAccountUpdateOptions {
/**
* The country the account holder resides in or that the business is legally
* established in. For example, if you are in the United States and the
* business you’re creating an account for is legally represented in Canada,
* you would use “CA” as the country for the account being created.
*/
country?: string;
/**
* The email address of the account holder. For standalone accounts, Stripe
* will email your user with instructions for how to set up their account. For
* managed accounts, this is only to make the account easier to identify to
* you: Stripe will never directly reach out to your users.
*/
email: string;
/**
* Whether you'd like to create a managed or standalone account. Managed
* accounts have extra parameters available to them, and require that you,
* the platform, handle all communication with the account holder.
* Standalone accounts are normal Stripe accounts: Stripe will email the
* account holder to setup a username and password, and handle all account
* management directly with them.
*/
managed?: boolean;
}
interface IAccountShared {
business_logo?: string;
/**
* The publicly sharable name for this account
*/
business_name?: string;
/**
* A CSS hex color value representing the primary branding color for this
* account
*/
business_primary_color?: string;
/**
* The URL that best shows the service or product provided for this account
*/
business_url?: string;
/**
* A boolean for whether or not Stripe should try to reclaim negative
* balances from the account holder’s bank account. See our managed
* account bank transfer guide for more information
*/
debit_negative_balances?: boolean;
/**
* Account-level settings to automatically decline certain types of charges
* regardless of the bank’s decision.
*/
decline_charge_on?: {
/**
* Whether or not Stripe should automatically decline charges with an
* incorrect zip/postal code. This setting only applies if a card includes a
* zip code and the bank specifically marks it as failed.
*/
avs_failure?: boolean;
/**
* Whether or not Stripe should automatically decline charges with an
* incorrect CVC. This setting only applies if a card includes a CVC and the
* bank specifically marks it as failed.
*/
cvc_failure?: boolean;
};
/**
* Three-letter ISO currency code representing the default currency for the
* account. This must be a currency that Stripe supports in the account’s
* country.
*/
default_currency?: string;
/**
* Email address of the account holder. For standalone accounts, this is used
* to email them asking them to claim their Stripe account. For managed
* accounts, this is only to make the account easier to identify to you: Stripe
* will not email the account holder.
*/
email?: string;
/**
* Information about the holder of this account, i.e. the user receiving funds
* from this account
*/
legal_entity?: {}; //TODO: Implement this type definition.
/**
* A set of key/value pairs that you can attach to an account object. It can be
* useful for storing additional information about the account in a structured
* format. This can be unset by updating the value to null and then saving.
*/
metadata?: IMetadata;
/**
* Internal-only description of the product being sold or service being
* provided by this account. It’s used by Stripe for risk and underwriting
* purposes.
*/
product_description?: string;
/**
* The text that will appear on credit card statements by default if a charge is
* being made directly on the account.
*/
statement_descriptor?: string;
/**
* A publicly shareable email address that can be reached for support for this
* account
*/
support_email?: string;
/**
* A publicly shareable phone number that can be reached for support for
* this account
*/
support_phone?: string;
/**
* A publicly shareable URL that can be reached for support for this account
*/
support_url?: string;
/**
* Details on who accepted the Stripe terms of service, and when they
* accepted it. See our updating managed accounts guide for more
* information
*/
tos_acceptance?: {
/**
* The unix timestamp that Stripe’s terms of service were agreed to by the
* account holder
*/
date: number;
/**
* The IP address from which Stripe’s terms of service were agreed to by the account holder
*/
ip?: string;
/**
* The user agent of the browser from which Stripe’s terms of service
* were agreed to by the account holder
*/
user_agent?: string;
};
/**
* Details on when this account will make funds from charges available, and
* when they will be paid out to the account holder’s bank account. See our
* managed account bank transfer guide for more information
*/
transfer_schedule?: {
/**
* The number of days charges for the account will be held before being
* paid out. May also be the string “minimum” for the lowest available
* value (based on country). Default is “minimum”. Does not apply when
* interval is “manual”.
*/
delay_days?: number | string;
/**
* How frequently funds will be paid out. One of "manual" (for only
* triggered via API call), "daily", "weekly", or "monthly". Default is "daily".
*/
interval?: string;
/**
* The day of the month funds will be paid out. Required and available
* only if interval is "monthly".
*/
monthly_anchor?: number;
/**
* The day of the week funds will be paid out, of the style ‘monday’,
* ‘tuesday’, etc. Required and available only if interval is weekly.
*/
weekly_anchor?: string;
}
}
interface IAccountUpdateOptions extends IDataOptions, IAccountShared {
/**
* A card or bank account to attach to the account. You can provide either a
* token, like the ones returned by Stripe.js, or a dictionary as documented in
* the external_account parameter for either card or bank account creation.
*
* This will create a new external account object, make it the new default
* external account for its currency, and delete the old default if one exists. If
* you want to add additional external accounts instead of replacing the
* existing default for this currency, use the bank account or card creation
* API.
*/
external_account?: {
/**
* The type of external account. Should be "bank_account".
*/
object: string;
/**
* The account number for the bank account in string form. Must be a
* checking account.
*/
account_number: string;
/**
* The country the bank account is in.
*/
country: string;
/**
* The currency the bank account is in. This must be a country/currency
* pairing that Stripe supports.
*/
currency: string;
/**
* The name of the person or business that owns the bank account. This
* field is required when attaching the bank account to a customer object.
*/
account_holder_name?: string;
/**
* The type of entity that holds the account. This can be either
* "individual" or "company". This field is required when attaching the
* bank account to a customer object.
*/
account_holder_type?: string;
/**
* The routing number, sort code, or other country-appropriate institution
* number for the bank account. For US bank accounts, this is required
* and should be the ACH routing number, not the wire routing number. If
* you are providing an IBAN for account_number, this field is not
* required.
*/
routing_number?: string;
}
}
interface IExternalAccountCreationOptions extends IDataOptionsWithMetadata {
/**
* When adding a card to a customer, the parameter name is source. When
* adding to an account, the parameter name is external_account. The
* value can either be a token, like the ones returned by our Stripe.js, or a
* dictionary containing a user’s credit card details (with the options shown
* below). Stripe will automatically validate the card.
*/
external_account: string ;
/**
* Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added
* in this currency) this card will become the default external account for its currency.
*/
default_for_currency?: boolean;
}
interface IExternalAccountUpdateOptions extends IDataOptionsWithMetadata {
/**
* If set to true, this bank account will become the default external account for its currency.
*/
default_for_currency?: boolean;
}
interface IBankAccountListOptions extends IListOptions {
object: "bank_account"
}
interface ICardListOptions extends IListOptions {
object: "card"
}
interface IRejectReason {
/**
* The reason for rejecting the account. May be one of "fraud",
* "terms_of_service", or "other".
*/
reason: "fraud" | "terms_of_service" | "other" ;
}
}
namespace applicationFees {
interface IApplicationFee extends IResourceObject {
/**
* Value is "application_fee"
*/
object: string;
/**
* ID of the Stripe account this fee was taken from. [Expandable]
*/
account: string | accounts.IAccount;
/**
* Amount earned, in cents/pence.
*/
amount: number;
/**
* Positive integer or zero
*/
amount_refunded: number;
/**
* ID of the Connect Application that earned the fee. [Expandable]
*/
application: string; //TODO: Implement IApplication interface and reference type here for expansion:- "string | IApplication"
/**
* Balance transaction that describes the impact of this collected application
* fee on your account balance (not including refunds). [Expandable]
*/
balance_transaction: string | balance.IBalanceTransaction;
/**
* ID of the charge that the application fee was taken from. [Expandable]
*/
charge: string | charges.ICharge;
created: number;
/**
* Three-letter ISO code representing the currency of the charge.
*/
currency: string;
livemode: boolean;
/**
* ID of the corresponding charge on the platform account, if this fee was the
* result of a charge using the destination parameter. [Expandable]
*/
originating_transaction: string;
/**
* Whether or not the fee has been fully refunded. If the fee is only partially
* refunded, this attribute will still be false.
*/
refunded: boolean;
/**
* A list of refunds that have been applied to the fee.
*/
refunds: IApplicationFeeRefunds;
}
interface IApplicationFeeListOptions extends IListOptionsCreated {
/**
* Only return application fees for the charge specified by this charge ID.
*/
charge: string;
}
interface IApplicationFeeRefund extends IResourceObject {
/**
* Value is "fee_refund"
*/
object:string;
/**
* Amount, in cents/pence.
*/
amount: number;
/**
* Balance transaction that describes the impact on your account balance.
*/
balance_transaction: string | balance.IBalanceTransaction;
created: number;
/**
* Three-letter ISO code representing the currency.
*/
currency: string;
/**
* ID of the application fee that was refunded.
*/
fee: string | IApplicationFee;
/**
* A set of key/value pairs that you can attach to the object. It can be useful
* for storing additional information in a structured format.
*/
metadata: IMetadata;
}
interface IApplicationFeeRefunds extends IList<IApplicationFeeRefund>, resources.ApplicationFeeRefunds { }
interface IApplicationFeeRefundCreationOptions extends IDataOptions {
/**
* A positive integer in pence representing how much of this fee to refund.
* Can only refund up to the unrefunded amount remaining of the fee.
*
* default is entire application fee
*/
amount?: number;
/**
* A set of key/value pairs that you can attach to a refund object. It can be
* useful for storing additional information about the refund in a structured
* format. You can unset an individual key by setting its value to null and
* then saving. To clear all keys, set metadata to null, then save.
*/
metadata?: IMetadata;
}
}
namespace balance {
interface IBalance extends IObject {
/**
* Value is 'balance'
*/
object: string;
/**
* Funds that are available to be paid out automatically by Stripe or explicitly
* via the transfers API. The available balance for each currency and payment
* type can be found in the source_types property.
*/
available: Array<ISourceType>;
livemode: boolean;
/**
* Funds that are not available in the balance yet, due to the 7-day rolling pay
* cycle. The pending balance for each currency and payment type can be
* found in the source_types property
*/
pending: Array<ISourceType>;
}
interface ISourceType {
currency: string;
amount: number;
source_types: {
card: number;
bitcoin_receiver?: number;
customer_bank_account?: number;
alipay_account?: number;
}
}
interface IBalanceTransaction extends IResourceObject {
/**
* Value is 'balance_transaction'
*/
object: string;
/**
* Gross amount of the transaction, in cents/pence.
*/
amount: number;
/**
* The date the transaction's net funds will become available in the Stripe balance.
*/
available_on: number;
created: number;
/**
* Three-letter ISO currency code representing the currency.
*/
currency: string;
description?: string;
/**
* Fee (in cents/pence) paid for this transaction
*/
fee: number;
/**
* Detailed breakdown of fees (in cents/pence) paid for this transaction
*/
fee_details: Array<{
amount: number;
application: string;
/**
* Three-letter ISO currency code representing the currency of the amount that was disputed.
*/
currency: string;
description: string;
/**
* Type of the fee, one of: "application_fee", "stripe_fee"" or "tax".
*/
type: string;
}>;
/**
* Net amount of the transaction, in cents.
*/
net: number;
/**
* The Stripe object this transaction is related to. [Expandable]
*/
source: string | IResourceObject;
/**
* The transfers (if any) for which source is a source_transaction.
*/
source_transfers: IList<transfers.ITransfer>;
/**
* If the transaction's net funds are available in the Stripe balance yet. Either "available" or "pending".
*/
status: string;
/**
* Transaction type: "adjustment", "application_fee",
* "application_fee_refund", "charge", "payment", "payment_refund",
* "refund", "transfer", "transfer_cancel", "transfer_failure", or
* "transfer_refund".
*/
type: string;
}
interface IBalanceListOptions extends IListOptions {
available_on?: string | IDateFilter;
currency?: string;
/**
* Only returns transactions that are related to the specified Stripe object ID
* (e.g. filtering by a charge ID will return all related charge transactions).
*/
source?: string;
/**
* For automatic Stripe transfers only, only returns transactions that were
* transferred out on the specified transfer ID.
*/
transfer?: string;
/**
* Only returns transactions of the given type. One of: "charge", "refund",
* "adjustment", "application_fee", "application_fee_refund", "transfer",
* or "transfer_failure"
*/
type?: string;
}
}
namespace charges {
/**
* To charge a credit or a debit card, you create a charge object. You can retrieve and refund individual
* charges as well as list all charges. Charges are identified by a unique random ID.
*/
interface ICharge extends IResourceObject {
/**
* Value is 'charge'
*/
object: "charge";
/**
* Amount charged in cents/pence, positive integer or zero.
*/
amount: number;
/**
* Amount in cents/pence refunded (can be less than the amount attribute on the
* charge if a partial refund was issued), positive integer or zero.
*/
amount_refunded: number;
/**
* The application fee (if any) for the charge. See the Connect documentation
* for details. [Expandable]
*/
application_fee?: string;
/**
* ID of the balance transaction that describes the impact of this charge on
* your account balance (not including refunds or disputes). [Expandable]
*/
balance_transaction: string | balance.IBalanceTransaction;
/**
* If the charge was created without capturing, this boolean represents whether or not it is
* still uncaptured or has since been captured.
*/
captured: boolean;
created: number;
/**
* Three-letter ISO currency code representing the currency in which the
* charge was made.
*/
currency: string;
/**
* ID of the customer this charge is for if one exists. [Expandable]
*/
customer: string | customers.ICustomer;
description?: string;
/**
* Details about the dispute if the charge has been disputed.
*/
dispute?: disputes.IDispute;
/**
* Error code explaining reason for charge failure if available (see the errors section for a list of
* codes: https://stripe.com/docs/api#errors).
*/
failure_code: string;
/**
* Message to user further explaining reason for charge failure if available.
*/
failure_message: string;
/**
* Hash with information on fraud assessments for the charge.
*/
fraud_details: {
/**
* Assessments reported by you have the key user_report and, if set, possible values of "safe" and "fraudulent".
*/
user_report?: "fraudulent" | "safe";
/**
* Assessments from Stripe have the key stripe_report and, if set, the value "fraudulent".
*/
stripe_report?: "fraudulent";
};
/**
* ID of the invoice this charge is for if one exists. [Expandable]
*/
invoice: string | invoices.IInvoice;
livemode: boolean;
metadata: IMetadata;
/**
* ID of the order this charge is for if one exists. [Expandable]
*/
order: string | orders.IOrder;
/**
* true if the charge succeeded, or was successfully authorized for later capture.
*/
paid: boolean;
/**
* This is the email address that the receipt for this charge was sent to.
*/
receipt_email: string;
/**
* This is the transaction number that appears on email receipts sent for this charge.
*/
receipt_number: string;
/**
* Whether or not the charge has been fully refunded. If the charge is only partially refunded,
* this attribute will still be false.
*/
refunded: boolean;
/**
* A list of refunds that have been applied to the charge.
*/
refunds: IChargeRefunds;
/**
* Shipping information for the charge.
*/
shipping?: IShippingInformation;
/**
* For most Stripe users, the source of every charge is a credit or debit card.
* This hash is then the card object describing that card.
*/
source: cards.ICard | bitcoinReceivers.IBitcoinReceiver;
/**
* The transfer ID which created this charge. Only present if the charge came
* from another Stripe account. See the Connect documentation for details.
* [Expandable]
*/
source_transfer: string | transfers.ITransfer;
/**
* Extra information about a charge. This will appear on your customer’s
* credit card statement.
*/
statement_descriptor: string;
/**
* The status of the payment is either "succeeded", "pending", or "failed".
*/
status: "succeeded" | "pending" | "failed";
/**
* ID of the transfer to the destination account (only applicable if the
* charge was created using the destination parameter). [Expandable]
*/
transfer: string | transfers.ITransfer;
}
interface IChargeCreationOptions extends IDataOptions {
/**
* A positive integer in the smallest currency unit (e.g 100 cents to charge
* $1.00, or 1 to charge ¥1, a 0-decimal currency) representing how much to
* charge the card. The minimum amount is £0.50 (or equivalent in charge
* currency).
*/
amount: number;
/**
* 3-letter ISO code for currency.
*/
currency: string;
/**
* A fee in pence that will be applied to the charge and transferred to the
* application owner's Stripe account. To use an application fee, the request
* must be made on behalf of another account, using the Stripe-Account
* header, an OAuth key, or the destination parameter. For more
* information, see the application fees documentation.
*
* Connect only.
*/
application_fee?: number;
/**
* Whether or not to immediately capture the charge. When false, the charge
* issues an authorization (or pre-authorization), and will need to be
* captured later. Uncaptured charges expire in 7 days. For more information,
* see authorizing charges and settling later.
*/
capture?: boolean;
/**
* An arbitrary string which you can attach to a charge object. It is displayed
* when in the web interface alongside the charge. Note that if you use Stripe
* to send automatic email receipts to your customers, your receipt emails
* will include the description of the charge(s) that they are describing.
*/
description?: string;
/**
* An account to make the charge on behalf of. If specified, the charge will be
* attributed to the destination account for tax reporting, and the funds from
* the charge will be transferred to the destination account. The ID of the
* resulting transfer will be returned in the transfer field of the response. See
* the documentation for details.
*
* Connect only.
*/
destination?: string;
/**
* A set of key/value pairs that you can attach to a charge object. It can be
* useful for storing additional information about the customer in a
* structured format. It's often a good idea to store an email address in
* metadata for tracking later.
*/
metadata?: IMetadata;
/**
* The email address to send this charge's receipt to. The receipt will not be
* sent until the charge is paid. If this charge is for a customer, the email
* address specified here will override the customer's email address.
* Receipts will not be sent for test mode charges. If receipt_email is
* specified for a charge in live mode, a receipt will be sent regardless of your
* email settings.
*/
receipt_email?: string;
/**
* Shipping information for the charge. Helps prevent fraud on charges for
* physical goods. For more information, see the Charge object
* documentation.
*/
shipping?: IShippingInformation;
/**
* The ID of an existing customer that will be charged in this request.
*/
customer?: string;
/**
* A payment source to be charged, such as a credit card. If you also pass a
* customer ID, the source must be the ID of a source belonging to the
* customer. Otherwise, if you do not pass a customer ID, the source you
* provide must either be a token, like the ones returned by Stripe.js, or a
* object containing a user's credit card details, with the options described
* below. Although not all information is required, the extra info helps
* prevent fraud.
*/
source?: sources.ISourceCreationOptions;
/**
* An arbitrary string to be displayed on your customer's credit card
* statement. This may be up to 22 characters. As an example, if your
* website is RunClub and the item you're charging for is a race ticket, you
* may want to specify a statement_descriptor of
* RunClub 5K race ticket. The statement description may not include
* <>"' characters, and will appear on your customer's statement in capital
* letters. Non-ASCII characters are automatically stripped. While most
* banks display this information consistently, some may display it
* incorrectly or not at all.
*/
statement_descriptor?: string;
}
interface IChargeUpdateOptions extends IDataOptionsWithMetadata {
/**
* An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge.
* Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description
* of the charge(s) that they are describing. This can be unset by updating the value to null and then saving.
*/
description?: string;
/**
* A set of key/value pairs you can attach to a charge giving information about its riskiness.
*/
fraud_details?: {
/**
* If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a
* charge is safe, include a user_report key with a value of safe. Note that you must refund a charge before setting
* the user_report to fraudulent. Stripe will use the information you send to improve our fraud detection algorithm
*/
user_report?: "fraudulent" | "safe";
}
/**
* This is the email address that the receipt for this charge will be sent to.
* If this field is updated, then a new email receipt will be sent to the updated address.
*/
receipt_email?: string;
/**
* Shipping information for the charge. Helps prevent fraud on charges for
* physical goods.
*/
shipping?: IShippingInformation;
}
interface IChargeListOptions extends IListOptionsCreated {
/**
* Only return charges for the customer specified by this customer ID.
*/
customer?: string;
/**
* A filter on the list based on the source of the charge. The value can be a
* dictionary with the following options:
*/
source?: {
/**
* Return charges that match this source type string. Available options are
* "all", "alipay_account", "bitcoin_receiver", or "card".
*/
object: "all" | "alipay_account" | "bitcoin_receiver" | "card";
}
}
interface IChargeRefunds extends IList<refunds.IRefund>, resources.ChargeRefunds { }
}
namespace coupons {
/**
* A discount represents the actual application of a coupon to a particular customer. It contains information
* about when the discount began and when it will end.
*/
interface IDiscount extends IObject {
/**
* Value is 'discount'
*/
object: "discount";
/**
* Hash describing the coupon applied to create this discount
*/
coupon: ICoupon;
customer: string;
/**
* If the coupon has a duration of once or repeating, the date that this discount will end. If the coupon
* used has a forever duration, this attribute will be null.
*/
end: number;
/**
* Date that the coupon was applied
*/
start: number;
/**
* The subscription that this coupon is applied to, if it is applied to a particular subscription
*/
subscription: string;
}
/**
* A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer.
* Coupons only apply to invoices; they do not apply to one-off charges.
*/
interface ICoupon extends IResourceObject {
/**
* Value is 'coupon'
*/
object: "coupon";
/**
* Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.
*/
amount_off: number;
created: number;
/**
* If amount_off has been set, the currency of the amount to take off.
*/
currency: string;
/**
* One of "forever", "once", and "repeating". Describes how long a customer who applies this coupon will get the discount.
*/
duration: "forever" | "once" | "repeating" ;
/**
* If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.
*/
duration_in_months: number;
livemode: boolean;
/**
* Maximum number of times this coupon can be redeemed, in total, before it is no longer valid.
*/
max_redemptions: number;
metadata: IMetadata;
/**
* Percent that will be taken off the subtotal of any invoices for this customer for the duration
* of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead.
*/
percent_off: number;
/**
* Date after which the coupon can no longer be redeemed
*/
redeem_by: number;
/**
* Number of times this coupon has been applied to a customer.
*/
times_redeemed: number;
/**
* Taking account of the above properties, whether this coupon can still be applied to a customer
*/
valid: boolean;
}
interface ICouponCreationOptions extends IDataOptionsWithMetadata {
/**
* Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific
* code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you
* can leave the ID blank and we’ll generate a random code for you.
*/
id?: string;
/**
* Specifies how long the discount will be in effect. Can be forever, once, or repeating.
*/
duration: "forever" | "once" | "repeating" ;
/**
* A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)
*/
amount_off?: number;
/**
* Currency of the amount_off parameter (required if amount_off is passed)
*/
currency?: string;
/**
* Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months
* the discount will be in effect.
*/
duration_in_months?: number;
/**
* A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid.
*
* For example, you might have a 50% off coupon that the first 20 readers of your blog can use.
*/
max_redemptions?: number;
/**
* A positive integer between 1 and 100 that represents the discount the coupon will apply (required if amount_off is not passed)
*/
percent_off?: number;
/**
* Unix timestamp specifying the last time at which the coupon can be redeemed.
* After the redeem_by date, the coupon can no longer be applied to new customers.
*/
redeem_by?: number;
}
}
namespace customers {
/**
* Customer objects allow you to perform recurring charges and track multiple charges that are associated
* with the same customer. The API allows you to create, delete, and update your customers. You can
* retrieve individual customers as well as a list of all your customers.
*/
interface ICustomer extends IResourceObject {
/**
* Value is 'customer'
*/
object: "customer";
/**
* Current balance, if any, being stored on the customer's account. If negative, the customer has credit to apply to
* the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance
* does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied
* to any invoice. This balance is only taken into account for recurring charges.
*/
account_balance?: number;
created: number;
/**
* The currency the customer can be charged in for recurring billing purposes (subscriptions, invoices, invoice items).
*/
currency: string;
/**
* ID of the default source attached to this customer. [Expandable]
*/
default_source: string | cards.ICard | bitcoinReceivers.IBitcoinReceiver;
/**
* Whether or not the latest charge for the customer's latest invoice has failed
*/
delinquent: boolean;
description?: string;
/**
* Describes the current discount active on the customer, if there is one.
*/
discount?: coupons.IDiscount;
email?: string;
livemode: boolean;
metadata?: IMetadata;
/**
* Shipping information associated with the customer.
*/
shipping: IShippingInformation;
/**
* The customer’s payment sources, if any
*/
sources?: IList<cards.ICard | bitcoinReceivers.IBitcoinReceiver>;
cards?: resources.CustomerCards;
/**
* The customer's current subscriptions, if any
*/
subscriptions: ICustomerSubscriptions;
}
interface ICustomerSubscriptions extends IList<subscriptions.ISubscription>, resources.CustomerSubscriptions {}
interface ICustomerCreationOptions extends IDataOptionsWithMetadata {
/**
* An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that
* will be used before attempting any charges to the customer's card; a positive amount will be added to the next invoice.
*/
account_balance?: number;
/**
* If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the
* API will not have the discount.
*/
coupon?: string;
/**
* An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This can
* be unset by updating the value to null and then saving.
*/
description?: string;
/**
* Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking.
* This can be unset by updating the value to null and then saving.
*/
email?: string;
/**
* The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions
* that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a
* valid card as well.
*/
plan?: string;
/**
* The quantity you'd like to apply to the subscription you're creating (if you pass in a plan). For example, if your plan is
* 10 cents/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged 50 cents
* (5 x 10 cents) monthly. Defaults to 1 if not set. Only applies when the plan parameter is also provided.
*/
quantity?: number;
shipping?: IShippingInformation;
/**
* The source can either be a token, like the ones returned by our Stripe.js, or
* a dictionary containing a user’s credit card details.
*/
source?: sources.ISourceCreationOptionsExtended;
/**
* A positive decimal (with at most two decimal places) between 1 and 100.
* This represents the percentage of the subscription invoice subtotal that
* will be calculated and added as tax to the final amount each billing period.
* For example, a plan which charges $10/month with a tax_percent of 20.0
* will charge $12 per invoice. Can only be used if a plan is provided.
*/
tax_percent?