/ 
Net-API-Stripe-v2.0.5
River stage one • 1 direct dependent • 1 total dependent
/ Net::API::Stripe::Customer

NAME

Net::API::Stripe::Customer - A Customer object in Stripe API

SYNOPSIS

my $cust = $stripe->customer({
    address => $address_object,
    balance => 20000,
    coupon => 'VIP2020_20POFF',
    currency => 'jpy',
    description => 'Webstore customer',
    email => 'john.doe@example.com',
    invoice_prefix => 'JD123',
    invoice_settings =>
        {
        # or it could just contain an id such as pm_fake124567890
        default_payment_method => $payment_method_object,
        footer => 'Big Corp, Inc web store',
        },
    metadata => { customer_id => 123 },
    name => 'John Doe',
    phone => '+81-(0)90-1234-5678',
    preferred_locales => [qw( ja en fr )],
    shipping => $address_object,
});

See documentation in Net::API::Stripe for example to make api calls to Stripe to create those objects.

VERSION

v0.101.0

DESCRIPTION

From the documentation:

Stripe Customer objects allow you to perform recurring charges, and to 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.

CONSTRUCTOR

new( %ARG )

Creates a new Net::API::Stripe::Customer object. It may also take an hash like arguments, that also are method of the same name.

METHODS

id string

Unique identifier for the object.

object string, value is "customer"

String representing the object’s type. Objects of the same type share the same value.

account_balance

It seems not in use anymore as of 2019-10-16, at least by the look of the API documentation.

address hash

The customer’s address. This is a Net::API::Stripe::Address object.

balance integer

Current balance, if any, being 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 will be added to their 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 as invoices are finalized.

cards

This represents a Net::API::Stripe::Customer::Sources object.

It seems that as of 2019-10-16, it is not in Stripe API, but it was seen in Stripe response.

cash_balance object

The current funds being held by Stripe on behalf of the customer. These funds can be applied towards payment intents with source "cashbalance".The settings[reconciliationmode] field describes whether these funds are applied to such payment intents manually or automatically.

This is a Net::API::Stripe::Cash::Balance object.

coupon optional

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.

This is used only when creating a customer object.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

currency string

Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.

default_card

The API does not mention this, but it was part of some response. Deprecated or omission?

default_source string (expandable)

ID of the default payment source for the customer. This is a Net::API::Stripe::Payment::Source object.

deleted

A flag that is being used, but not part of the API documentation.

delinquent boolean

When the customer’s latest invoice is billed by charging automatically, delinquent is true if the invoice’s latest charge is failed. When the customer’s latest invoice is billed by sending an invoice, delinquent is true if the invoice is not paid by its due date.

description string

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

discount hash, discount object

Describes the current discount active on the customer, if there is one. This is a Net::API::Stripe::Billing::Discount object.

email string

The customer’s email address.

invoice_credit_balance hash

The current multi-currency balances, if any, being 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 will be added to their next invoice denominated in that currency. These balances do not refer to any unpaid invoices.They solely track amounts that have yet to be successfully applied to any invoice. A balance in a particular currency is only applied to any invoice as an invoice in that currency is finalized.

invoice_prefix string

The prefix for the customer used to generate unique invoice numbers. This prefix must be unique otherwise it will generated an error such as This invoice number prefix is taken by customer: cus_fake1234567890. Please enter a different prefix

invoice_settings hash

The customer’s default invoice settings. This is a Net::API::Stripe::Billing::Invoice::Settings object.

custom_fields array of hashes

Default custom fields to be displayed on invoices for this customer. This is an array of Net::API::Stripe::CustomField object.

name string

The name of the custom field.

value string

The value of the custom field.

default_payment_method string (expandable)

ID of the default payment method used for subscriptions and invoices for the customer. When expanded, this is a Net::API::Stripe::Payment::Method object.

Default footer to be displayed on invoices for this customer.

livemode boolean

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

metadata hash

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.

name string

The customer’s full name or business name.

next_invoice_sequence string

The sequence to be used on the customer’s next invoice. Defaults to 1.

payment_method optional

The ID of the PaymentMethod to attach to the customer.

This is used when creating a customer object.

phone string

The customer’s phone number.

preferred_locales array containing strings

The customer’s preferred locales (languages), ordered by preference.

shipping hash

Mailing and shipping address for the customer. Appears on invoices emailed to this customer. This is a Net::API::Stripe::Shipping object.

source optional

A Token’s (https://stripe.com/docs/api#tokens) or a Source’s (https://stripe.com/docs/api#sources) ID, as returned by Elements (https://stripe.com/docs/elements). Passing source will create a new source object, make it the new customer default source, and delete the old customer default if one exists. If you want to add additional sources instead of replacing the existing default, use the card creation API (https://stripe.com/docs/api#create_card). Whenever you attach a card to a customer, Stripe will automatically validate the card.

This is used when creating a customer object.

sources list

The customer’s payment sources, if any. This is a Net::API::Stripe::Customer::Sources object.

subscriptions list

The customer’s current subscriptions, if any. This is a Net::API::Stripe::List object of Net::API::Stripe::Billing::Subscription objects.

tax object

Tax details for the customer.

This is a Net::API::Stripe::Terminal::Reader object.

tax_exempt string

Describes the customer’s tax exemption status. One of none, exempt, or reverse. When set to reverse, invoice and receipt PDFs include the text “Reverse charge”.

tax_id_data optional array of hashes

The customer’s tax IDs.

This is used when creating a customer object.

type required

Type of the tax ID, one of au_abn, ch_vat, eu_vat, in_gst, mx_rfc, no_vat, nz_gst, or za_vat

value required

Value of the tax ID.

tax_ids list

The customer’s tax IDs. This is represented by a Net::API::Stripe::Customer::TaxIds object.

object string, value is "list"

String representing the object's type. Objects of the same type share the same value. Always has the value list.

data array of Net::API::Stripe::Customer::TaxId object
has_more boolean

True if this list has another page of items after this one that can be fetched.

url string

The URL where this list can be accessed.

tax_info deprecated hash

The customer’s tax information. Appears on invoices emailed to this customer. This field has been deprecated and will be removed in a future API version, for further information view the migration guide.

This is a Net::API::Stripe::Customer::TaxInfo object.

tax_info_verification deprecated hash

Describes the status of looking up the tax ID provided in tax_info. This field has been deprecated and will be removed in a future API version, for further information view the migration guide.

This is a Net::API::Stripe::Customer::TaxInfoVerification object

test_clock expandable

ID of the test clock this customer belongs to.

When expanded this is an Net::API::Stripe::Billing::TestHelpersTestClock object.

API SAMPLE

{
  "id": "cus_fake123456789",
  "object": "customer",
  "account_balance": 0,
  "address": null,
  "balance": 0,
  "created": 1571176460,
  "currency": "jpy",
  "default_source": null,
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": null,
  "invoice_prefix": "0822CFA",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null
  },
  "livemode": false,
  "metadata": {},
  "name": null,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/customers/cus_fake123456789/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/customers/cus_fake123456789/subscriptions"
  },
  "tax_exempt": "none",
  "tax_ids": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/customers/cus_fake123456789/tax_ids"
  },
  "tax_info": null,
  "tax_info_verification": null
}

HISTORY

v0.1

Initial version

STRIPE HISTORY

2019-12-03

Deprecated tax information for Customers have been removed.

The deprecated tax_info and tax_info_verification fields on the Customer object are now removed in favor of tax_ids.
The deprecated tax_info parameter on the Customer create and update methods are removed in favor of tax_id_data.
For more information, view the migration guide.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Stripe API documentation:

https://stripe.com/docs/api/customers

COPYRIGHT & LICENSE

Copyright (c) 2019-2020 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.