Checkout
The Session object

The Session object

The Session object is a view of the Checkout Session API object and represents your customer's session on your checkout page.

Because data can change over the lifecycle of a session, avoid storing a reference to the Session object. Instead, call session() to retrieve the current value and listen to the change event to subscribe to updates.

Object Properties

  •  id string

    The ID of the Checkout Session.

  •  billingAddress nullable object

    Billing details of the Customer.

    Hide billingAddress properties

    •  name nullable string

      Full name.

    •  address nullable object

      Address.

      Hide address properties

      •  country string

        Two-letter country code (ISO 3166-1 alpha-2).

      •  line1 nullable string

        Address line 1 (e.g., street, PO Box, or company name).

      •  line2 nullable string

        Address line 2 (e.g., apartment, suite, unit, or building).

      •  city nullable string

        City, district, suburb, town, or village.

      •  postal_code nullable string

        ZIP or postal code.

      •  state nullable string

        State, county, province, or region.

  •  businessName nullable string

    The business name as configured in the Business Public Details settings of your Stripe account.

  •  canConfirm boolean

    Whether the Checkout Session has collected enough data to confirm. Use this field to indicate to your customer if they can proceed, such as disabling the pay button.

  •  currency enum

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  •  currencyOptions nullable array of objects

    The currency options available on the Checkout Session when using Adaptive Pricing.

    Hide currencyOptions properties

    •  amount string

      A formatted string representing the total amount in the source currency, including currency symbols.

    •  minorUnitsAmount integer

      An integer representing the total amount in the source currency in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  currency enum

      Three-letter ISO currency code, in lowercase.

    •  currencyConversion optional object

      Currency conversion details. This is only present for the customer currency.

      Hide currencyConversion properties

      •  fxRate decimal string

        The exchange rate used to convert source currency amounts to customer currency amounts.

      •  sourceCurrency enum

        The creation currency of the Checkout Session before localization.

  •  discountAmounts array of objects

    The aggregate amounts calculated per discount for all line items.

    Hide discountAmounts properties

    •  amount string

      A formatted string representing the discount amount, including currency symbols.

    •  minorUnitsAmount integer

      An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  displayName string

      A user-facing description of the discount.

    •  promotionCode nullable string

      The customer-facing promotion code that was used to apply this discount, if any.

    •  recurring nullable object

      Details of how the discount applies to recurring payments.

      Hide recurring properties

      •  type enum

        One of forever or repeating.

        • forever: Applies to all charges from a subscription with this coupon applied.
        • repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.

      •  durationInMonths nullable integer

        If duration is repeating, the number of months the coupon applies. Null otherwise.

    •  percentOff nullable integer

      An integer representing the discount amount as a percentage.

  •  email nullable string

    The Customer's email address.

  •  lastPaymentError nullable object

    The error encountered the last time the Checkout Session was confirmed.

    Hide lastPaymentError properties

    •  message string

      An error message to be displayed to the customer.

  •  lineItems array of objects

    A list of items the customer is purchasing.

    Hide lineItems properties

    •  id string

      Unique identifier for the object.

    •  subtotal nullable object

      Total before any discounts or exclusive taxes are applied.

      Hide subtotal properties

      •  amount string

        A formatted string representing the subtotal amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  discount nullable object

      Total discount amount. A positive number reduces the amount to be paid.

      Hide discount properties

      •  amount string

        A formatted string representing the discount amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  taxExclusive nullable object

      Total amount of exclusive tax (tax that is collected in addition to the subtotal).

      Hide taxExclusive properties

      •  amount string

        A formatted string representing the exclusive tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  taxInclusive nullable object

      Total amount of inclusive tax (tax that is already included in the subtotal).

      Hide taxInclusive properties

      •  amount string

        A formatted string representing the inclusive tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  total nullable object

      Total amount for this line item, including discounts and tax.

      Hide total properties

      •  amount string

        A formatted string representing the total amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  unitAmount nullable object

      The amount representing the cost of a single unit of the item.

      Hide unitAmount properties

      •  amount string

        A formatted string representing the unit amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  description optional string

      An arbitrary string attached to the object. Often useful for displaying to users.

    •  name string

      The item's name, meant to be displayable to users.

    •  images array of strings

      An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session.

    •  quantity integer

      The quantity of products being purchased.

    •  discountAmounts array of objects

      The amount of discount calculated per discount for this line item.

      Hide discountAmounts properties

      •  amount string

        A formatted string representing the discount amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  displayName string

        A user-facing description of the discount.

      •  promotionCode nullable string

        The customer-facing promotion code that was used to apply this discount, if any.

      •  recurring nullable object

        Details of how the discount applies to recurring payments.

        Hide recurring properties

        •  type enum

          One of forever or repeating.

          • forever: Applies to all charges from a subscription with this coupon applied.
          • repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.

        •  durationInMonths nullable integer

          If duration is repeating, the number of months the coupon applies. Null otherwise.

      •  percentOff nullable integer

        An integer representing the discount amount as a percentage.

    •  taxAmounts nullable array of objects

      The amount of tax calculated per tax rate for this line item.

      Hide taxAmounts properties

      •  amount string

        A formatted string representing the tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  inclusive boolean

        Whether this tax amount is inclusive or exclusive.

      •  displayName string

        A user-facing description of the tax.

    •  recurring nullable object

      The recurring components of a price such as interval and intervalCount.

      Hide recurring properties

      •  interval enum

        Specifies billing frequency. Either day, week, month, or year.

      •  intervalCount integer

        The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.

      •  usageType enum

        One of licensed or metered. licensed automatically bills the quantity set when adding it to a subscription. metered aggregates the total usage based on usage records.

      •  isProrated boolean

        When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor.

    •  adjustableQuantity nullable object

      Configuration for this item's quantity to be adjusted by the customer during checkout.

      Hide adjustableQuantity properties

      •  maximum integer

        The maximum quantity the customer can purchase for the Checkout Session.

      •  minimum integer

        The minimum quantity the customer can purchase for the Checkout Session.

  •  livemode boolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  •  minorUnitsAmountDivisor integer

    The factor used to convert between minor and major currency units.

    This value represents the number of minor currency units per one major unit. For example, in USD, where cents are the minor unit, the divisor is 100. In JPY, which has no minor units, the divisor is 1.

  •  phoneNumber nullable string

    The Customer's phone number.

  •  recurring object

    Details about recurring payments set up by the Checkout Session.

    Hide recurring properties

    •  interval enum

      Specifies billing frequency. Either day, week, month, or year.

    •  intervalCount integer

      The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.

    •  dueNext object

      Details about the next scheduled recurring payment.

      Hide dueNext properties

      •  subtotal nullable object

        Total before any discounts or exclusive taxes are applied.

        Hide subtotal properties

        •  amount string

          A formatted string representing the subtotal amount, including currency symbols.

        •  minorUnitsAmount integer

          An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  discount nullable object

        Total discount amount. A positive number reduces the amount to be paid.

        Hide discount properties

        •  amount string

          A formatted string representing the discount amount, including currency symbols.

        •  minorUnitsAmount integer

          An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  taxExclusive nullable object

        Total amount of exclusive tax (tax that is collected in addition to the subtotal).

        Hide taxExclusive properties

        •  amount string

          A formatted string representing the exclusive tax amount, including currency symbols.

        •  minorUnitsAmount integer

          An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  taxInclusive nullable object

        Total amount of inclusive tax (tax that is already included in the subtotal).

        Hide taxInclusive properties

        •  amount string

          A formatted string representing the inclusive tax amount, including currency symbols.

        •  minorUnitsAmount integer

          An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  billingCycleAnchor nullable integer

        A future Unix timestamp to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. If not present, the subscription starts immediately.

    •  trial nullable object

      Details about a free trial, if there is one.

      Hide trial properties

      •  trialEnd integer

        Unix timestamp representing the end of the trial period the customer will get before being charged for the first time.

      •  trialPeriodDays integer

        Integer representing the number of trial period days before the customer is charged for the first time.

  •  savedPaymentMethods array of objects

    An array of payment methods attached to the Customer.

    Hide savedPaymentMethods properties

    •  id string

      ID of the PaymentMethod object

    •  type enum

      The type of the PaymentMethod

    •  billingDetails object

      Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

      Hide billingDetails properties

      •  email nullable string

        Email address.

      •  phone nullable string

        Billing phone number (including extension).

      •  name nullable string

        Full name.

      •  address nullable object

        Address.

        Hide address properties

        •  country string

          Two-letter country code (ISO 3166-1 alpha-2).

        •  line1 nullable string

          Address line 1 (e.g., street, PO Box, or company name).

        •  line2 nullable string

          Address line 2 (e.g., apartment, suite, unit, or building).

        •  city nullable string

          City, district, suburb, town, or village.

        •  postal_code nullable string

          ZIP or postal code.

        •  state nullable string

          State, county, province, or region.

    •  card object

      If this is a card PaymentMethod, this hash contains the user's card details.

      Hide card properties

      •  brand string

        The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards. Can be american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa, or other and may contain more values in the future.

      •  expMonth integer

        Two-digit number representing the card's expiration month.

      •  expYear integer

        Four-digit number representing the card's expiration year.

      •  last4 string

        The last four digits of the card.

  •  shipping nullable object

    The selected shipping option, if any.

    Hide shipping properties

    •  shippingOption object

      Details of the selected shipping option.

      Hide shippingOption properties

      •  id string

        Unique identifier for the object.

      •  amount string

        A formatted string representing the shipping amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  currency string

        Three-letter ISO currency code, in lowercase.

      •  displayName nullable string

        A user-facing description of the shipping option.

      •  deliveryEstimate nullable object

        The estimated range for how long shipping will take.

        Hide deliveryEstimate properties

        •  maximum nullable object

          The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

          Hide maximum properties

          •  unit string

            A unit of time. Either business_day, day, hour, week, or month.

          •  value integer

            Must be greater than 0.

        •  minimum nullable object

          The lower bound of the estimated range. If empty, represents no lower bound.

          Hide minimum properties

          •  unit string

            A unit of time. Either business_day, day, hour, week, or month.

          •  value integer

            Must be greater than 0.

    •  taxAmounts array of objects

      The amount of tax calculated per tax rate for shipping costs.

      Hide taxAmounts properties

      •  amount string

        A formatted string representing the tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

      •  inclusive boolean

        Whether this tax amount is inclusive or exclusive.

      •  displayName string

        A user-facing description of the tax.

  •  shippingAddress nullable object

    Shipping address of the Customer.

    Hide shippingAddress properties

    •  name nullable string

      Full name.

    •  address nullable object

      Address.

      Hide address properties

      •  country string

        Two-letter country code (ISO 3166-1 alpha-2).

      •  line1 string

        Address line 1 (e.g., street, PO Box, or company name).

      •  line2 nullable string

        Address line 2 (e.g., apartment, suite, unit, or building).

      •  city nullable string

        City, district, suburb, town, or village.

      •  postal_code nullable string

        ZIP or postal code.

      •  state nullable string

        State, county, province, or region.

  •  shippingOptions array of objects

    The list of shipping options that can be selected.

    Hide shippingOptions properties

    •  id string

      Unique identifier for the object.

    •  amount string

      A formatted string representing the shipping amount, including currency symbols.

    •  minorUnitsAmount integer

      An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  currency string

      Three-letter ISO currency code, in lowercase.

    •  displayName nullable string

      A user-facing description of the shipping option.

    •  deliveryEstimate nullable object

      The estimated range for how long shipping will take.

      Hide deliveryEstimate properties

      •  maximum nullable object

        The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

        Hide maximum properties

        •  unit string

          A unit of time. Either business_day, day, hour, week, or month.

        •  value integer

          Must be greater than 0.

      •  minimum nullable object

        The lower bound of the estimated range. If empty, represents no lower bound.

        Hide minimum properties

        •  unit string

          A unit of time. Either business_day, day, hour, week, or month.

        •  value integer

          Must be greater than 0.

  •  status object

    Status of the Checkout Session.

    Hide status properties

    •  type enum

      One of open, expired, or complete.

      • open: The Checkout Session is still in progress.
      • expired: The Checkout Session has expired. No further processing will occur.
      • complete: The Checkout Session is complete. Payment processing may still be in progress.

    •  paymentStatus nullable enum

      One of paid, unpaid, or no_payment_required. Only present when type=complete.

      • paid: The payment funds are available in your account.
      • unpaid: The payment funds are not yet available in your account.
      • no_payment_required: The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn't require a payment at this time.

  •  tax object

    Details about the tax computation status.

    Hide tax properties

    •  status enum

      One of ready, requires_shipping_address, or requires_billing_address.

      • ready: The final tax amount is computed, and the session is ready for confirmation.
      • requires_shipping_address: A shipping address must be provided to calculate tax.
      • requires_billing_address: A billing address must be provided to calculate tax.

  •  taxAmounts nullable array of objects

    The aggregate amounts calculated per tax rate for all line items. This value is null if tax has not yet been computed, i.e. the Customer's address has not been collected yet.

    Hide taxAmounts properties

    •  amount string

      A formatted string representing the tax amount, including currency symbols.

    •  minorUnitsAmount integer

      An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  inclusive boolean

      Whether this tax amount is inclusive or exclusive.

    •  displayName string

      A user-facing description of the tax.

  •  total object

    Tax and discount details for the computed total amount. Use this field to render an amount breakdown to your customer, such as in an order summary.

    Hide total properties

    •  subtotal object

      The total amount of line items, excluding tax, discounts, and shipping.

      Hide subtotal properties

      •  amount string

        A formatted string representing the subtotal amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  taxExclusive object

      The sum of all exclusive tax amounts

      Hide taxExclusive properties

      •  amount string

        A formatted string representing the exclusive tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  taxInclusive object

      The sum of all inclusive tax amounts

      Hide taxInclusive properties

      •  amount string

        A formatted string representing the inclusive tax amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  shippingRate object

      The sum of all shipping amounts.

      Hide shippingRate properties

      •  amount string

        A formatted string representing the total shipping amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  discount object

      The sum of all the discounts. A positive number reduces the amount to be paid.

      Hide discount properties

      •  amount string

        A formatted string representing the discount amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  total object

      Total computed amount, including discounts and tax.

      Hide total properties

      •  amount string

        A formatted string representing the total amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  appliedBalance object

      Total amount of customer credit balance to be applied to the payment. A positive number increases the amount to be paid, and a negative number decreases the amount to be paid.

      Hide appliedBalance properties

      •  amount string

        A formatted string representing the applied customer balance amount, including currency symbols.

      •  minorUnitsAmount integer

        An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    •  balanceAppliedToNextInvoice boolean

      When true, no payment will be collected immediately. Instead, the amount due will be added to the Customer's next invoice. This can happen when the amount due today is less than the minimum chargeable amount.