Create a customer 

Parameters

• addressobjectRequired if calculating taxes

  The customer’s address.

  Hide child parameters

  • address.citystring

    City, district, suburb, town, or village.

  • address.countrystringRequired if calculating taxes

    A freeform text field for the country. However, in order to activate some tax features, the format should be a two-letter country code (ISO 3166-1 alpha-2).

  • address.line1string

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

  • address.line2string

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

  • address.postal_codestringRequired if calculating taxes

    ZIP or postal code.

  • address.statestring

    State, county, province, or region.

• descriptionstring

  An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

• emailstring

  Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to 512 characters.

• metadataobject

  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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• namestring

  The customer’s full name or business name.

• payment_methodstring

  The ID of the PaymentMethod to attach to the customer.

• phonestring

  The customer’s phone number.

• shippingobject

  The customer’s shipping information. Appears on invoices emailed to this customer.

  Hide child parameters

  • shipping.addressobjectRequired

    Customer shipping address.

    Hide child parameters

    • shipping.address.citystring

      City, district, suburb, town, or village.

    • shipping.address.countrystringRequired if calculating taxes

      A freeform text field for the country. However, in order to activate some tax features, the format should be a two-letter country code (ISO 3166-1 alpha-2).

    • shipping.address.line1string

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

    • shipping.address.line2string

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

    • shipping.address.postal_codestringRequired if calculating taxes

      ZIP or postal code.

    • shipping.address.statestring

      State, county, province, or region.

  • shipping.namestringRequired

    Customer name.

  • shipping.phonestring

    Customer phone (including extension).

• taxobjectRecommended if calculating taxes

  Tax details about the customer.

  Hide child parameters

  • tax.ip_addressstring

    A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes.

  • tax.validate_locationenum

    A flag that indicates when Stripe should validate the customer tax location. Defaults to deferred.

    Possible enum values

    deferred Defer the validation of the customer’s tax location until needed, such as when Stripe Tax is calculating taxes on an Invoice. Default.

    immediately Validate the customer’s tax location immediately. An error is returned and the customer is not created/updated if the tax location is invalid. Recommended if calculating taxes.

More parameters

Collapse all

• balanceinteger

  An integer amount in cents that represents the customer’s current balance, which affect the customer’s future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

• cash_balanceobject

  Balance information and default balance settings for this customer.

  Hide child parameters

  • cash_balance.settingsobject

    Settings controlling the behavior of the customer’s cash balance, such as reconciliation of funds received.

    Hide child parameters

    • cash_balance.settings.reconciliation_modeenum

      Controls how funds transferred by the customer are applied to payment intents and invoices. Valid options are automatic, manual, or merchant_default. For more information about these reconciliation modes, see Reconciliation.

      Possible enum values

      automatic

      manual

      merchant_default

• invoice_prefixstring

  The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.

• invoice_settingsobject

  Default invoice settings for this customer.

  Hide child parameters

  • invoice_settings.custom_fieldsarray of objects

    The list of up to 4 default custom fields to be displayed on invoices for this customer. When updating, pass an empty string to remove previously-defined fields.

    Hide child parameters

    • invoice_settings.custom_fields.namestringRequired

      The name of the custom field. This may be up to 40 characters.

    • invoice_settings.custom_fields.valuestringRequired

      The value of the custom field. This may be up to 140 characters.

  • invoice_settings.default_payment_methodstring

    ID of a payment method that’s attached to the customer, to be used as the customer’s default payment method for subscriptions and invoices.

  • invoice_settings.footerstring

    Default footer to be displayed on invoices for this customer.

  • invoice_settings.rendering_optionsobject

    Default options for invoice PDF rendering for this customer.

    Hide child parameters

    • invoice_settings.rendering_options.amount_tax_displayenum

      How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of exclude_tax or include_inclusive_tax. include_inclusive_tax will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. exclude_tax will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts.

      Possible enum values

      exclude_tax

      include_inclusive_tax

    • invoice_settings.rendering_options.templatestring

      ID of the invoice rendering template to use for future invoices.

• next_invoice_sequenceinteger

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

• preferred_localesarray of strings

  Customer’s preferred languages, ordered by preference.

• sourcestring

  When using payment sources created via the Token or Sources APIs, 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. Whenever you attach a card to a customer, Stripe will automatically validate the card.

• tax_exemptenum

  The customer’s tax exemption. One of none, exempt, or reverse.

  Possible enum values

  exempt

  none

  reverse

• tax_id_dataarray of objects

  The customer’s tax IDs.

  Hide child parameters

  • tax_id_data.typestringRequired

    Type of the tax ID, one of ad_nrt, ae_trn, al_tin, am_tin, ao_tin, ar_cuit, au_abn, au_arn, aw_tin, az_tin, ba_tin, bb_tin, bd_bin, bf_ifu, bg_uic, bh_vat, bj_ifu, bo_tin, br_cnpj, br_cpf, bs_tin, by_tin, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, cd_nif, ch_uid, ch_vat, cl_tin, cm_niu, cn_tin, co_nit, cr_tin, cv_nif, de_stn, do_rcn, ec_ruc, eg_tin, es_cif, et_tin, eu_oss_vat, eu_vat, gb_vat, ge_vat, gn_nif, hk_br, hr_oib, hu_tin, id_npwp, il_vat, in_gst, is_vat, jp_cn, jp_rn, jp_trn, ke_pin, kg_tin, kh_tin, kr_brn, kz_bin, la_tin, li_uid, li_vat, ma_vat, md_vat, me_pib, mk_vat, mr_nif, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, np_pan, nz_gst, om_vat, pe_ruc, ph_tin, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sn_ninea, sr_fin, sv_nit, th_vat, tj_tin, tr_tin, tw_vat, tz_vat, ua_vat, ug_tin, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, za_vat, zm_tin, or zw_tin

  • tax_id_data.valuestringRequired

    Value of the tax ID.

• test_clockstring

  ID of the test clock to attach to the customer.