Create a Customer

POSThttps://api.omise.co/customers

Create a customer profile to save payment methods for repeat billing. Customers can have multiple saved cards and make future purchases without re-entering card details.

---

🔑API Credentials

▼

---

Request Parameters

Recommended - 2 fieldsRecommended Parameters

▼

`email`STRING(optional)

Customer email address. Used for receipts, refund notifications, and support.

Example:"john@example.com"

`description`STRING(optional)

Customer name or description. Helps identify customers in your dashboard and reports.

Example:"John Doe"

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Customer created successfully

Customer profile created. The customer ID should be stored in your database for future charges.

Customer object fields:

• id - Customer ID (cust_*). Store this in your database.
• email - Customer email address.
• description - Customer description/name.
• default_card - ID of the default payment card (if card was provided).
• cards - List object containing all saved cards.
• metadata - Custom key-value data.

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid email format
• Invalid token ID
• Metadata exceeds 15,000 characters

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Token not found or invalid.

Common causes:

• Token ID does not exist
• Token has already been used
• Token has expired

---

Code samples

cURL

curl https://api.omise.co/customers \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "email=john@example.com" \
  -d "description=John Doe" \
  -d "card=tokn_test_5xuy4w91xqz7d1w9u0t"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

customer = Omise::Customer.create({
  email: 'john@example.com',
  description: 'John Doe',
  card: 'tokn_test_5xuy4w91xqz7d1w9u0t'
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

customer = omise.Customer.create(
    email='john@example.com',
    description='John Doe',
    card='tokn_test_5xuy4w91xqz7d1w9u0t'
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const customer = await omise.customers.create({
  email: 'john@example.com',
  description: 'John Doe',
  card: 'tokn_test_5xuy4w91xqz7d1w9u0t'
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$customer = OmiseCustomer::create([
    'email' => 'john@example.com',
    'description' => 'John Doe',
    'card' => 'tokn_test_5xuy4w91xqz7d1w9u0t'
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Customer customer = client.customers().create()
    .email("john@example.com")
    .description("John Doe")
    .card("tokn_test_5xuy4w91xqz7d1w9u0t")
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var customer = await client.Customers.Create(new CreateCustomerRequest
{
    Email = "john@example.com",
    Description = "John Doe",
    Card = "tokn_test_5xuy4w91xqz7d1w9u0t"
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

customer, _ := client.Customers().Create(&operations.CreateCustomer{
    Email:       "john@example.com",
    Description: "John Doe",
    Card:        "tokn_test_5xuy4w91xqz7d1w9u0t",
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check email format and metadata size
authentication_failure	Invalid API key	Verify your secret key is correct
used_token	Token has already been used	Generate a new token
token_not_found	Token ID does not exist	Verify token ID is correct
invalid_card	Card token is invalid	Check token was created successfully

Customer Fields

Field	Description
id	Customer ID (store this in your database)
email	Customer email address
description	Customer name or description
default_card	ID of default payment card
cards	List of all saved cards
metadata	Custom key-value data
created_at	Customer creation timestamp

---

Try it out

Recommended - 2 fields

▼

Additional - 2 fields

▼