Class Customer

All Implemented Interfaces:
HasId, MetadataStore<Customer>, StripeActiveObject, StripeObjectInterface

public class Customer extends ApiResource implements HasId, MetadataStore<Customer>
This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.

Related guide: Save a card during payment

  • Constructor Details

    • Customer

      public Customer()
  • Method Details

    • getDefaultSource

      public String getDefaultSource()
      Get ID of expandable defaultSource object.
    • setDefaultSource

      public void setDefaultSource(String id)
    • getDefaultSourceObject

      public PaymentSource getDefaultSourceObject()
      Get expanded defaultSource.
    • setDefaultSourceObject

      public void setDefaultSourceObject(PaymentSource expandableObject)
    • getTestClock

      public String getTestClock()
      Get ID of expandable testClock object.
    • setTestClock

      public void setTestClock(String id)
    • getTestClockObject

      public TestClock getTestClockObject()
      Get expanded testClock.
    • setTestClockObject

      public void setTestClockObject(TestClock expandableObject)
    • balanceTransactions

      public CustomerBalanceTransactionCollection balanceTransactions() throws StripeException
      Returns a list of transactions that updated the customer’s balances.
      Throws:
      StripeException
    • balanceTransactions

      public CustomerBalanceTransactionCollection balanceTransactions(Map<String,Object> params) throws StripeException
      Returns a list of transactions that updated the customer’s balances.
      Throws:
      StripeException
    • balanceTransactions

      public CustomerBalanceTransactionCollection balanceTransactions(Map<String,Object> params, RequestOptions options) throws StripeException
      Returns a list of transactions that updated the customer’s balances.
      Throws:
      StripeException
    • balanceTransactions

      Returns a list of transactions that updated the customer’s balances.
      Throws:
      StripeException
    • balanceTransactions

      Returns a list of transactions that updated the customer’s balances.
      Throws:
      StripeException
    • cashBalanceTransactions

      public CustomerCashBalanceTransactionCollection cashBalanceTransactions() throws StripeException
      Returns a list of transactions that modified the customer’s cash balance.
      Throws:
      StripeException
    • cashBalanceTransactions

      public CustomerCashBalanceTransactionCollection cashBalanceTransactions(Map<String,Object> params) throws StripeException
      Returns a list of transactions that modified the customer’s cash balance.
      Throws:
      StripeException
    • cashBalanceTransactions

      public CustomerCashBalanceTransactionCollection cashBalanceTransactions(Map<String,Object> params, RequestOptions options) throws StripeException
      Returns a list of transactions that modified the customer’s cash balance.
      Throws:
      StripeException
    • cashBalanceTransactions

      Returns a list of transactions that modified the customer’s cash balance.
      Throws:
      StripeException
    • cashBalanceTransactions

      Returns a list of transactions that modified the customer’s cash balance.
      Throws:
      StripeException
    • create

      public static Customer create(Map<String,Object> params) throws StripeException
      Creates a new customer object.
      Throws:
      StripeException
    • create

      public static Customer create(Map<String,Object> params, RequestOptions options) throws StripeException
      Creates a new customer object.
      Throws:
      StripeException
    • create

      public static Customer create(CustomerCreateParams params) throws StripeException
      Creates a new customer object.
      Throws:
      StripeException
    • create

      public static Customer create(CustomerCreateParams params, RequestOptions options) throws StripeException
      Creates a new customer object.
      Throws:
      StripeException
    • createFundingInstructions

      public FundingInstructions createFundingInstructions(Map<String,Object> params) throws StripeException
      Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
      Throws:
      StripeException
    • createFundingInstructions

      public FundingInstructions createFundingInstructions(Map<String,Object> params, RequestOptions options) throws StripeException
      Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
      Throws:
      StripeException
    • createFundingInstructions

      public FundingInstructions createFundingInstructions(CustomerCreateFundingInstructionsParams params) throws StripeException
      Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
      Throws:
      StripeException
    • createFundingInstructions

      public FundingInstructions createFundingInstructions(CustomerCreateFundingInstructionsParams params, RequestOptions options) throws StripeException
      Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.
      Throws:
      StripeException
    • delete

      public Customer delete() throws StripeException
      Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
      Throws:
      StripeException
    • delete

      public Customer delete(RequestOptions options) throws StripeException
      Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
      Throws:
      StripeException
    • delete

      public Customer delete(Map<String,Object> params) throws StripeException
      Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
      Throws:
      StripeException
    • delete

      public Customer delete(Map<String,Object> params, RequestOptions options) throws StripeException
      Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
      Throws:
      StripeException
    • deleteDiscount

      public Discount deleteDiscount() throws StripeException
      Removes the currently applied discount on a customer.
      Throws:
      StripeException
    • deleteDiscount

      public Discount deleteDiscount(Map<String,Object> params) throws StripeException
      Removes the currently applied discount on a customer.
      Throws:
      StripeException
    • deleteDiscount

      public Discount deleteDiscount(Map<String,Object> params, RequestOptions options) throws StripeException
      Removes the currently applied discount on a customer.
      Throws:
      StripeException
    • list

      public static CustomerCollection list(Map<String,Object> params) throws StripeException
      Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
      Throws:
      StripeException
    • list

      public static CustomerCollection list(Map<String,Object> params, RequestOptions options) throws StripeException
      Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
      Throws:
      StripeException
    • list

      public static CustomerCollection list(CustomerListParams params) throws StripeException
      Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
      Throws:
      StripeException
    • list

      public static CustomerCollection list(CustomerListParams params, RequestOptions options) throws StripeException
      Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
      Throws:
      StripeException
    • listPaymentMethods

      public PaymentMethodCollection listPaymentMethods() throws StripeException
      Returns a list of PaymentMethods for a given Customer.
      Throws:
      StripeException
    • listPaymentMethods

      public PaymentMethodCollection listPaymentMethods(Map<String,Object> params) throws StripeException
      Returns a list of PaymentMethods for a given Customer.
      Throws:
      StripeException
    • listPaymentMethods

      public PaymentMethodCollection listPaymentMethods(Map<String,Object> params, RequestOptions options) throws StripeException
      Returns a list of PaymentMethods for a given Customer.
      Throws:
      StripeException
    • listPaymentMethods

      Returns a list of PaymentMethods for a given Customer.
      Throws:
      StripeException
    • listPaymentMethods

      public PaymentMethodCollection listPaymentMethods(CustomerListPaymentMethodsParams params, RequestOptions options) throws StripeException
      Returns a list of PaymentMethods for a given Customer.
      Throws:
      StripeException
    • retrieve

      public static Customer retrieve(String customer) throws StripeException
      Retrieves a Customer object.
      Throws:
      StripeException
    • retrieve

      public static Customer retrieve(String customer, RequestOptions options) throws StripeException
      Retrieves a Customer object.
      Throws:
      StripeException
    • retrieve

      public static Customer retrieve(String customer, Map<String,Object> params, RequestOptions options) throws StripeException
      Retrieves a Customer object.
      Throws:
      StripeException
    • retrieve

      public static Customer retrieve(String customer, CustomerRetrieveParams params, RequestOptions options) throws StripeException
      Retrieves a Customer object.
      Throws:
      StripeException
    • retrievePaymentMethod

      public PaymentMethod retrievePaymentMethod(String paymentMethod) throws StripeException
      Retrieves a PaymentMethod object for a given Customer.
      Throws:
      StripeException
    • retrievePaymentMethod

      public PaymentMethod retrievePaymentMethod(String paymentMethod, Map<String,Object> params) throws StripeException
      Retrieves a PaymentMethod object for a given Customer.
      Throws:
      StripeException
    • retrievePaymentMethod

      public PaymentMethod retrievePaymentMethod(String paymentMethod, Map<String,Object> params, RequestOptions options) throws StripeException
      Retrieves a PaymentMethod object for a given Customer.
      Throws:
      StripeException
    • retrievePaymentMethod

      public PaymentMethod retrievePaymentMethod(String paymentMethod, CustomerRetrievePaymentMethodParams params) throws StripeException
      Retrieves a PaymentMethod object for a given Customer.
      Throws:
      StripeException
    • retrievePaymentMethod

      public PaymentMethod retrievePaymentMethod(String paymentMethod, CustomerRetrievePaymentMethodParams params, RequestOptions options) throws StripeException
      Retrieves a PaymentMethod object for a given Customer.
      Throws:
      StripeException
    • search

      public static CustomerSearchResult search(Map<String,Object> params) throws StripeException
      Search for customers you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
      Throws:
      StripeException
    • search

      public static CustomerSearchResult search(Map<String,Object> params, RequestOptions options) throws StripeException
      Search for customers you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
      Throws:
      StripeException
    • search

      public static CustomerSearchResult search(CustomerSearchParams params) throws StripeException
      Search for customers you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
      Throws:
      StripeException
    • search

      public static CustomerSearchResult search(CustomerSearchParams params, RequestOptions options) throws StripeException
      Search for customers you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
      Throws:
      StripeException
    • update

      public Customer update(Map<String,Object> params) throws StripeException
      Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled will be retried. This retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer will not trigger this behavior.

      This request accepts mostly the same arguments as the customer creation call.

      Specified by:
      update in interface MetadataStore<Customer>
      Throws:
      StripeException
    • update

      public Customer update(Map<String,Object> params, RequestOptions options) throws StripeException
      Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled will be retried. This retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer will not trigger this behavior.

      This request accepts mostly the same arguments as the customer creation call.

      Specified by:
      update in interface MetadataStore<Customer>
      Throws:
      StripeException
    • update

      public Customer update(CustomerUpdateParams params) throws StripeException
      Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled will be retried. This retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer will not trigger this behavior.

      This request accepts mostly the same arguments as the customer creation call.

      Throws:
      StripeException
    • update

      public Customer update(CustomerUpdateParams params, RequestOptions options) throws StripeException
      Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled will be retried. This retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer will not trigger this behavior.

      This request accepts mostly the same arguments as the customer creation call.

      Throws:
      StripeException
    • getTestHelpers

      public Customer.TestHelpers getTestHelpers()
      The customer's state, county, province, or region as identified by Stripe Tax.
    • setResponseGetter

      public void setResponseGetter(StripeResponseGetter responseGetter)
      Description copied from interface: StripeActiveObject
      Method is used by the containing object or StripeResponseGetter implementations to set the StripeResponseGetter instance used to make further requests.
      Specified by:
      setResponseGetter in interface StripeActiveObject
      Overrides:
      setResponseGetter in class ApiResource
      Parameters:
      responseGetter - the StripeResponseGetter instance to use for making further requests.
    • getAddress

      public Address getAddress()
      The customer's address.
    • getBalance

      public Long getBalance()
      The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
    • getCashBalance

      public CashBalance getCashBalance()
      The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The settings[reconciliation_mode] field describes if these funds apply to these payment intents manually or automatically.
    • getCreated

      public Long getCreated()
      Time at which the object was created. Measured in seconds since the Unix epoch.
    • getCurrency

      public String getCurrency()
      Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.
    • getDeleted

      public Boolean getDeleted()
      Always true for a deleted object.
    • getDelinquent

      public Boolean getDelinquent()
      Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the invoice.due_date will set this field to true.

      If an invoice becomes uncollectible by dunning, delinquent doesn't reset to false.

      If you care whether the customer has paid their most recent subscription invoice, use subscription.status instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to false.

    • getDescription

      public String getDescription()
      An arbitrary string attached to the object. Often useful for displaying to users.
    • getDiscount

      public Discount getDiscount()
      Describes the current discount active on the customer, if there is one.
    • getEmail

      public String getEmail()
      The customer's email address.
    • getInvoiceCreditBalance

      public Map<String,Long> getInvoiceCreditBalance()
      The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
    • getInvoicePrefix

      public String getInvoicePrefix()
      The prefix for the customer used to generate unique invoice numbers.
    • getInvoiceSettings

      public Customer.InvoiceSettings getInvoiceSettings()
    • getLivemode

      public Boolean getLivemode()
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.
    • getName

      public String getName()
      The customer's full name or business name.
    • getNextInvoiceSequence

      public Long getNextInvoiceSequence()
      The suffix of the customer's next invoice number (for example, 0001).
    • getObject

      public String getObject()
      String representing the object's type. Objects of the same type share the same value.

      Equal to customer.

    • getPhone

      public String getPhone()
      The customer's phone number.
    • getPreferredLocales

      public List<String> getPreferredLocales()
      The customer's preferred locales (languages), ordered by preference.
    • getShipping

      public ShippingDetails getShipping()
      Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
    • getSources

      public PaymentSourceCollection getSources()
      The customer's payment sources, if any.
    • getSubscriptions

      public SubscriptionCollection getSubscriptions()
      The customer's current subscriptions, if any.
    • getTax

      public Customer.Tax getTax()
    • getTaxExempt

      public String getTaxExempt()
      Describes the customer's tax exemption status, which is none, exempt, or reverse. When set to reverse, invoice and receipt PDFs include the following text: "Reverse charge".

      One of exempt, none, or reverse.

    • getTaxIds

      public TaxIdCollection getTaxIds()
      The customer's tax IDs.
    • setAddress

      public void setAddress(Address address)
      The customer's address.
    • setBalance

      public void setBalance(Long balance)
      The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
    • setCashBalance

      public void setCashBalance(CashBalance cashBalance)
      The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The settings[reconciliation_mode] field describes if these funds apply to these payment intents manually or automatically.
    • setCreated

      public void setCreated(Long created)
      Time at which the object was created. Measured in seconds since the Unix epoch.
    • setCurrency

      public void setCurrency(String currency)
      Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.
    • setDeleted

      public void setDeleted(Boolean deleted)
      Always true for a deleted object.
    • setDelinquent

      public void setDelinquent(Boolean delinquent)
      Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the invoice.due_date will set this field to true.

      If an invoice becomes uncollectible by dunning, delinquent doesn't reset to false.

      If you care whether the customer has paid their most recent subscription invoice, use subscription.status instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to false.

    • setDescription

      public void setDescription(String description)
      An arbitrary string attached to the object. Often useful for displaying to users.
    • setDiscount

      public void setDiscount(Discount discount)
      Describes the current discount active on the customer, if there is one.
    • setEmail

      public void setEmail(String email)
      The customer's email address.
    • setId

      public void setId(String id)
      Unique identifier for the object.
    • setInvoiceCreditBalance

      public void setInvoiceCreditBalance(Map<String,Long> invoiceCreditBalance)
      The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
    • setInvoicePrefix

      public void setInvoicePrefix(String invoicePrefix)
      The prefix for the customer used to generate unique invoice numbers.
    • setInvoiceSettings

      public void setInvoiceSettings(Customer.InvoiceSettings invoiceSettings)
    • setLivemode

      public void setLivemode(Boolean livemode)
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.
    • setMetadata

      public void setMetadata(Map<String,String> metadata)
      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
    • setName

      public void setName(String name)
      The customer's full name or business name.
    • setNextInvoiceSequence

      public void setNextInvoiceSequence(Long nextInvoiceSequence)
      The suffix of the customer's next invoice number (for example, 0001).
    • setObject

      public void setObject(String object)
      String representing the object's type. Objects of the same type share the same value.

      Equal to customer.

    • setPhone

      public void setPhone(String phone)
      The customer's phone number.
    • setPreferredLocales

      public void setPreferredLocales(List<String> preferredLocales)
      The customer's preferred locales (languages), ordered by preference.
    • setShipping

      public void setShipping(ShippingDetails shipping)
      Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
    • setSources

      public void setSources(PaymentSourceCollection sources)
      The customer's payment sources, if any.
    • setSubscriptions

      public void setSubscriptions(SubscriptionCollection subscriptions)
      The customer's current subscriptions, if any.
    • setTax

      public void setTax(Customer.Tax tax)
    • setTaxExempt

      public void setTaxExempt(String taxExempt)
      Describes the customer's tax exemption status, which is none, exempt, or reverse. When set to reverse, invoice and receipt PDFs include the following text: "Reverse charge".

      One of exempt, none, or reverse.

    • setTaxIds

      public void setTaxIds(TaxIdCollection taxIds)
      The customer's tax IDs.
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • canEqual

      protected boolean canEqual(Object other)
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • getId

      public String getId()
      Unique identifier for the object.
      Specified by:
      getId in interface HasId
    • getMetadata

      public Map<String,String> getMetadata()
      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
      Specified by:
      getMetadata in interface MetadataStore<Customer>