Add or create Customers with basic details such as name, email and contact details. You can then offer various Razorpay solutions to your customers. Edit customer details as needed.

You can try out our APIs on the Razorpay Postman Public Workspace.

Use Cases🔗

Add or create a customer by providing basic details such as name, email and contact information to use them for the various Razorpay solutions.
Edit the existing customer details.
Retrieve information about all customers.
Retrieve details for a specific customer using the unique identifier linked to the customer.

Customer Entity🔗

The Customer entity has the following fields:

id: string Unique identifier of the customer. For example, cust_1Aa00000000004.
name: string Customer's name. Alphanumeric, with period (.), apostrophe (') and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.
contact: string The customer's phone number. A maximum length of 15 characters including country code. For example, +919876543210.
email: string The customer's email address. A maximum length of 64 characters. For example, gaurav.kumar@example.com.
gstin: string GST number linked to the customer. For example, 29XAbbA4369J1PA.
notes: 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”.
created_at: integer UNIX timestamp, when the customer was created. For example, 1234567890.

 Sample Entity
Copy{
  "id": "cust_JbRkXMROZUMCVq",
  "entity": "customer",
  "name": "Gauri Kumari",
  "email": "gauri.kumari@example.com",
  "contact": "9123456789",
  "gstin": null,
  "notes": [],
  "created_at": 1653915355
}

You can create and manage customer using APIs or from the Razorpay Dashboard.

Create a Customer🔗

The following endpoint creates or add a customer with basic details such as name and contact details. You can use this API for various Razorpay Solution offerings.

/customers

 Curl Java Python Go PHP .NET Ruby Node.JS Response
Copycurl -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",
  "gstin":"29XAbbA4369J1PA",
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  }
}'
CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

JSONObject request = new JSONObject();
request.put("name", <name>);
request.put("email", <email>);

Customer customer = razorpayClient.Customers.create(request);

Copyimport 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,
  "gstin": "29XAbbA4369J1PA",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
})

Copyimport ( 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)

Copy$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'));

CopyRazorpayClient client = new RazorpayClient(your_key_id, your_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);

Copyrequire "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customer = Razorpay::Customer.create email: 'gaurav.kumar@example.com', contact: '9123456780'
puts customer.id #cust_6vRXClWqnLhV14

Copyvar 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,
  gstin: "29XAbbA4369J1PA",
  notes: {
    notes_key_1: "Tea, Earl Grey, Hot",
    notes_key_2: "Tea, Earl Grey… decaf."
  }
})

Copy{
  "id" : "cust_1Aa00000000004",
  "entity": "customer",
  "name" : "Gaurav Kumar",
  "email" : "gaurav.kumar@example.com",
  "contact" : "9123456780",
  "gstin": "29XAbbA4369J1PA",
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  },
  "created_at ": 1234567890
}

Request Parameters🔗

name mandatory

string Customer's name. Alphanumeric value with period (.), apostrophe (') and parentheses are allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.

contact optional

string The customer's phone number. A maximum length of 15 characters including country code. For example, +919876543210.

email optional

string The customer's email address. A maximum length of 64 characters. For example, gaurav.kumar@example.com.

fail_existing optional

string Possible values:

0: If a customer with the same details already exists, fetches details of the existing customer.
1 (default): If a customer with the same details already exists, throws an error.

gstin optional

string Customer's GST number, if available. For example, 29XAbbA4369J1PA.

notes optional

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”.

Response Parameters🔗

Descriptions for the response parameters are present in the Customers Entity parameters table.

Edit Customer Details🔗

The following endpoint edits the customer details such as name, email and contact details.

/customers/:id

Handy Tips
When editing a customer's details, ensure that the combination of the values in the email and contact attributes is unique for a customer.

 Curl Java Python Go PHP Node.JS Response
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X PUT https://api.razorpay.com/v1/customers/cust_1Aa00000000003 \
-H "Content-Type: application/json" \
-d '{
  "name" : "Gaurav Kumar",
  "email" : "Gaurav.Kumar@example.com",
  "contact" : "9000000000"
}

CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

JSONObject request = new JSONObject();
request.put("name", <name>);
request.put("email", <email>);
Customer customer = razorpayClient.Customers.edit(customerId, request);

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.customer.edit(customerId,{
  "name": "Gaurav Kumar",
  "email": "Gaurav.Kumar@example.com",
  "contact": 9000000000
})

Copyimport ( 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)

Copy$api = new Api($key_id, $secret);

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

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.edit(customerId,{
  name: "Gaurav Kumar",
  email: "Gaurav.Kumar@example.com",
  contact: 9000000000
})

Copy{
  "id":"cust_1Aa00000000003",
  "entity":"customer",
  "name":"Gaurav Kumar",
  "email":"Gaurav.Kumar@example.com",
  "contact":"9000000000",
  "gstin":null,
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  },
  "created_at":1582033731

Path Parameter🔗

id mandatory: string The unique identifier linked to the customer.

Request Parameters🔗

name: string Customer's name. Alphanumeric, with period (.), apostrophe (') and parentheses allowed. The name must be between 3-50 characters in length. For example, Gaurav Kumar.
contact: string The customer's phone number. A maximum length of 15 characters. For example, +919876543210.
email: string The customer's email address. A maximum length of 64 characters. For example, gaurav.kumar@example.com.

Response Parameters🔗

Descriptions for the response parameters are present in the Customers Entity parameters table.

Fetch all Customers🔗

The following endpoint retrieves the details of all the customers.

/customers

Query Parameters🔗

count: integer The number of customer records to be retrieved from the system. The default value is 10. The maximum value is 100. This can be used for pagination in combination with skip.
skip: integer The number of customer records that must be skipped. The default value is 0. This can be used for pagination in combination with count.

Response Parameters🔗

Descriptions for the response parameters are present in the Customers Entity parameters table.

 Curl Python Go PHP Node.JS Response
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/customers?count=2&skip=1

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.customer.all(options)

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

optional := map[string]interface{}{
	  "count":1,
	}

body, err := client.Customer.All(optional, nil)

Copy$api = new Api($key_id, $secret);

$api->customer->all($options)

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.all(options)

Copy{
  "entity":"collection",
  "count":2,
  "items":[
    {
      "id":"cust_1Aa00000000001",
      "entity":"customer",
      "name":"Gaurav Kumar",
      "email":"gaurav.kumar@example.com",
      "contact":"9876543210",
      "gstin":"29XAbbA4369J1PA",
      "notes":{
        "note_key_1":"September",
        "note_key_2":"Make it so."
      },
      "created_at ":1234567890
    },
    {
      "id":"cust_1Aa00000000002",
      "entity":"customer",
      "name":"Asa Fox",
      "email":"asa.fox@example.com",
      "contact":"9123456789",
      "gstin":null,
      "notes":[],
      "created_at ":1234567890
    }
  ]
}

Fetch Customer by ID🔗

The following endpoint retrieves details of a customer as per the ID.

/customers/:id

 Curl Java Python Go PHP Node.JS Response
Copycurl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/customers/cust_1Aa00000000001 \

CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

Customer customer = razorpayClient.Customers.fetch(customerId);

Copyimport razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.customer.fetch(customerId)

Copyimport ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

customerId := "cust_1Aa00000000001"

body, err := client.Customer.Fetch(customerId, nil)

Copy$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)

Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.fetch(customerId)

Copy{
  "id" : "cust_1Aa00000000001",
  "entity": "customer",
  "name" : "Saurav Kumar",
  "email" : "Saurav.kumar@example.com",
  "contact" : "+919000000000",
  "gstin":"29XAbbA4369J1PA",
  "notes" : [],
  "created_at ": 1234567890
}

Path Parameter🔗

id mandatory: string The unique identifier linked to the customer.

Response Parameters🔗

Descriptions for the response parameters are present in the Customers Entity parameters table.