Create a customer

Creates a new customer object.

POST /v1/customers

CURL

curl https://{provided url}/v1/customers \
  -u sk_test_yFStF-KUmgr-7CoumuY2JA: \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d first_name=John \
  -d [email protected] \
  -d source=9TDphrhSQ9mHsFztnRxXbg \
  -d last_name=Doe \
  -d currency=usd
  -d phone=[phone] \
  -d address_line1=Address line 1 \
  -d address_city=City example \
  -d address_country=pl \
  -d address_line2=Address line 2 \
  -d address_zip=03-5896 \
  -d address_state=sk \
  -d metadata[id]=merchant_customer_id

The above command returns JSON structured like this:

{
	"id": "P2ZTA56JQ7-AvwGf0pHd2Q",
	"first_name": "John",
	"last_name": "Doe",
	"email": "[email protected]",
	"phone": "[phone]",
	"currency": "usd",
	"created_at": 1568895751,
	"default_source": "-7c66LB0TWCPZBNyXw4SAA",
	"address_line1": "Address line 1",
	"address_city": "City example",
	"address_country": "PL",
	"address_line2": "Address line 2",
	"address_zip": "03-5896",
	"address_state": "sk",
	"description": "",
	"metadata[id]": "merchant_customer_id"
}

Arguments

Parameter	Type	Required	Description
first_name	string	optional	The customer’s first name.
last_name	string	optional	Customer last name.
email	string	optional	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. This will be unset if you POST an empty value.
currency	string	optional	Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.
phone	string	optional	The customer’s phone number. This will be unset if you POST an empty value.
default_locale	string	optional	Customer’s preferred default language.
description	string	optional	An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.
address	dictionary	optional	The customer’s address.
source	string	optional	The source can be a Token or a Source, as returned by Elements. You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer to be charged automatically for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, API will automatically validate the card.
metadata	hash	optional	Contain the key, value pair with merchant information that will be linked to the customer.

Returns

Returns a customer object if the call succeeded. The returned object will have information about token sources, if that information has been provided. If a source has been attached to the customer, the returned customer object will have a default_source attribute, which is an ID that can be expanded into the full source details when retrieving the customer.