> For the complete documentation index, see [llms.txt](https://developer.convergegate.com/legacy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.convergegate.com/legacy/token-api/customers/create-a-customer.md).

# Create a customer

Creates a new customer object.

<mark style="color:yellow;">`POST`</mark>` ``/v1/customers`

{% tabs %}
{% tab title="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=john.doe@example.com \
  -d source=9TDphrhSQ9mHsFztnRxXbg \
  -d last_name=Doe \
  -d currency=usd
  -d phone=+48-7589658478 \
  -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
```

{% endtab %}
{% endtabs %}

The above command returns JSON structured like this:

```json
{
	"id": "P2ZTA56JQ7-AvwGf0pHd2Q",
	"first_name": "John",
	"last_name": "Doe",
	"email": "john.doe@example.com",
	"phone": "+48-7589658478",
	"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

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>first_name</td><td>string</td><td>optional</td><td>The customer’s first name.</td></tr><tr><td>last_name</td><td>string</td><td>optional</td><td>Customer last name.</td></tr><tr><td>email</td><td>string</td><td>optional</td><td>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.</td></tr><tr><td>currency</td><td>string</td><td>optional</td><td>Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.</td></tr><tr><td>phone</td><td>string</td><td>optional</td><td>The customer’s phone number. This will be unset if you POST an empty value.</td></tr><tr><td>default_locale</td><td>string</td><td>optional</td><td>Customer’s preferred default language.</td></tr><tr><td>description</td><td>string</td><td>optional</td><td>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.</td></tr><tr><td>address</td><td>dictionary</td><td>optional</td><td>The customer’s address.</td></tr><tr><td>source</td><td>string</td><td>optional</td><td>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.</td></tr><tr><td>metadata</td><td>hash</td><td>optional</td><td>Contain the key, value pair with merchant information that will be linked to the customer.</td></tr></tbody></table>

## Returns <a href="#returns" id="returns"></a>

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.