> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Customer

> Create a Customer using Razorpay Customers API.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
  <span>🇸🇬 Singapore</span>
  <span>🇺🇸 United States</span>
</div>

Use this endpoint to create or add a customer with basic details such as name and contact details.

<RequestExample>
  ```bash Curl theme={null}
  curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
  -X POST https://api.razorpay.com/v1/customers \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Gaurav Kumar",
      "contact": "9123456780",
      "email": "gaurav.kumar@example.com",
      "fail_existing": "0",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey… decaf."
    }
  }'
  ```

  ```java Java theme={null}
  RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

  JSONObject customerRequest = new JSONObject();
  customerRequest.put("name","Gaurav Kumar");
  customerRequest.put("contact","9123456780");
  customerRequest.put("email","gaurav.kumar@example.com");
  customerRequest.put("fail_existing","0");
  JSONObject notes = new JSONObject();
  notes.put("notes_key_1","Tea, Earl Grey, Hot");
  notes.put("notes_key_2","Tea, Earl Grey… decaf.");
  customerRequest.put("notes",notes);

  Customer customer = razorpay.customers.create(customerRequest);
  ```

  ```python Python theme={null}
  import razorpay
  client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

  client.customer.create({
    "name": "Gaurav Kumar",
    "contact": 9123456780,
    "email": "gaurav.kumar@example.com",
    "fail_existing": "0",
    "notes": {
      "notes_key_1": "Tea, Earl Grey, Hot",
      "notes_key_2": "Tea, Earl Grey… decaf."
    }
  })
  ```

  ```go Go theme={null}
  import ( razorpay "github.com/razorpay/razorpay-go" )
  client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

  data := map[string]interface{}{
      "name": "Gaurav Kumar",
      "contact": 9123456780,
      "email": "gaurav.kumar@example.com",
      "fail_existing": "0",
      "notes": map[string]interface{}{
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey… decaf.",
  	},
  }

  body, err := client.Customer.Create(data, nil)
  ```

  ```php PHP theme={null}
  $api = new Api($key_id, $secret);

  $api->customer->create(array('name' => 'Gaurav Kumar', 'email' => 'gaurav.kumar@example.com','contact'=>'9123456780','notes'=> array('notes_key_1'=> 'Tea, Earl Grey, Hot','notes_key_2'=> 'Tea, Earl Grey… decaf'));
  ```

  ```csharp .NET theme={null}
  RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

  Dictionary<string, object> options = new Dictionary<string,object>();

  options.Add("name", "Gaurav Kumar"); 
  options.Add("contact", "9123456780"); 
  options.Add("email", "gaurav.kumar@example.com"); 
  options.Add("fail_existing", "0"); 

  Customer customer = Customer.Create(options);
  ```

  ```ruby Ruby theme={null}
  require "razorpay"
  Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

  Razorpay::Customer.create({
    "name": "Gaurav Kumar",
    "contact": 9123456780,
    "email": "gaurav.kumar@example.com",
    "fail_existing": "0",
    "notes": {
      "notes_key_1": "Tea, Earl Grey, Hot",
      "notes_key_2": "Tea, Earl Grey… decaf."
    }
  })
  ```

  ```javascript Node.js theme={null}
  var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

  instance.customers.create({
    name: "Gaurav Kumar",
    contact: 9123456780,
    email: "gaurav.kumar@example.com",
    fail_existing: "0",
    notes: {
      notes_key_1: "Tea, Earl Grey, Hot",
      notes_key_2: "Tea, Earl Grey… decaf."
    }
  })
  ```

  ```bash CLI theme={null}
  razorpay customers create --name "Gaurav Kumar" --contact "+919123456780" --email "gaurav.kumar@example.com" --gstin "29XAbbA4369J1PA" --note key1="Test customer"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "id" : "cust_1Aa00000000004",
    "entity": "customer",
    "name" : "<name>",
    "email" : "<email>",
    "contact" : "<phone>",
    "gstin": null,
    "notes": {
      "notes_key_1":"Tea, Earl Grey, Hot",
      "notes_key_2":"Tea, Earl Grey… decaf."
    },
    "created_at ": 1234567890
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "Contact number should be at least 8 digits, including country code",
      "source": "business",
      "step": "NA",
      "reason": "invalid_contact_number",
      "metadata": {},
      "field": "contact"
    }
  }
  ```
</ResponseExample>

## Request Parameters

<ParamField body="name" type="string">
  Customer's name. Alphanumeric value with period (.), apostrophe ('), forward slash (/), at (@) and parentheses are allowed. The name must be between 3-50 characters in length. For example, `Gaurav Kumar`.
</ParamField>

<ParamField body="contact" type="string">
  The customer's phone number. A maximum length of 15 characters including country code. For example, `+919876543210`.
</ParamField>

<ParamField body="email" type="string">
  The customer's email address. A maximum length of 64 characters. For example, `gaurav.kumar@example.com`.
</ParamField>

<ParamField body="fail_existing" type="string">
  Possible values:

  * `1` (default): If a customer with the same details already exists, throws an error.
  * `0`: If a customer with the same details already exists, fetches details of the existing customer.
</ParamField>

<ParamField body="gstin" type="string">
  Customer's GST number, if available. For example, `29XAbbA4369J1PA`.
</ParamField>

<ParamField body="notes" type="object">
  This is a key-value pair that can be used to store additional information about the entity. It can hold a maximum of 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  Unique identifier of the customer. For example, `cust_1Aa00000000004`.
</ResponseField>

<ResponseField name="entity" type="string">
  Indicates the type of entity.
</ResponseField>

<ResponseField name="name" type="string">
  Customer's name. Alphanumeric, with period (.), apostrophe ('), forward slash (/), at (@) and parentheses allowed. The name must be between 3-50 characters in length.
</ResponseField>

<ResponseField name="contact" type="string">
  The customer's phone number. A maximum length of 15 characters including country code.
</ResponseField>

<ResponseField name="email" type="string">
  The customer's email address. A maximum length of 64 characters.
</ResponseField>

<ResponseField name="gstin" type="string">
  GST number linked to the customer. For example, `29XAbbA4369J1PA`.
</ResponseField>

<ResponseField name="notes" type="object">
  This is a key-value pair that can be used to store additional information about the entity. It can hold a maximum of 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  UNIX timestamp, when the customer was created. For example, `1234567890`.
</ResponseField>

<ResponseField name="shipping_address" type="object">
  The customer's shipping address. An address object with `line1`, `line2`, `city`, `state`, `country`, and `zipcode` fields. Empty when none is set.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion
    title="The API `<key/secret>
` provided is invalid."
  >
    **Code:** `4xx`

    The API credentials passed in the API call differ from the ones generated on the Dashboard. Possible reasons:

    * Different keys for test mode and live modes.
    * Expired API key.

    **Solution:** The API keys must be active and entered correctly with no whitespace before or after the keys.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Contact number should be at least 8 digits, including country code.">
    **Code:** `400`

    The contact number is less than 8 digits.

    **Solution:** Enter contact number that meets the validation criteria. It should have at least 8 digits, including the country code. For example, "+919876543210".
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="The email must be a valid email address.">
    **Code:** `400`

    The value passed for `email` is not in a valid email format.

    **Solution:** Pass a valid email address (for example, `user@example.com`).
  </Accordion>

  <Accordion title="Contact number contains invalid characters, only digits and + symbol are allowed.">
    **Code:** `400`

    The `contact` value contains characters other than digits and the `+` symbol (for example, letters, hyphens or spaces).

    **Solution:** Pass `contact` using only digits and an optional leading `+` for the country code.
  </Accordion>

  <Accordion title="The name may not be greater than 50 characters.">
    **Code:** `400`

    The `name` value exceeds the 50-character limit.

    **Solution:** Keep the `name` to 50 characters or fewer.
  </Accordion>

  <Accordion title="Customer already exists for the merchant.">
    **Code:** `400`

    A customer with the same `contact` or `email` already exists for this merchant and `fail_existing` was set to `1` (or omitted, which defaults to fail).

    **Solution:** Either use a different `contact` / `email`, or pass `fail_existing: "0"` in the request body to receive the existing customer in the response instead of an error.
  </Accordion>

  <Accordion title="Notes should not have more than 15 keys.">
    **Code:** `400`

    The `notes` object contains more than 15 key-value pairs.

    **Solution:** Reduce the number of keys in the `notes` object to 15 or fewer.
  </Accordion>

  <Accordion title="The name format is invalid.">
    **Code:** `400`

    The `name` value contains characters outside the allowed set. Allowed characters are letters, numbers and a limited set of punctuation (`'`, `-`, `.`, `_`, `(`, `)`, `@`, `/` and spaces). The name must start and end with a letter, number, `.` or `)`.

    **Solution:** Pass `name` using only the allowed characters and ensure it starts and ends with a letter, number, `.` or `)`.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="The gstin field is invalid.">
    **Code:** `400`

    The `gstin` value is not a valid Indian GSTIN. A GSTIN is a 15-character alphanumeric code in the format `<state-code><PAN><entity-code><check-digit>`.

    **Solution:** Pass a valid 15-character GSTIN.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Notes value cannot be greater than 512 characters.">
    **Code:** `400`

    One of the values inside the `notes` object exceeds the 512-character limit per value.

    **Solution:** Keep each `notes` value under 512 characters.
  </Accordion>
</AccordionGroup>