Customer API

⚠️

Don't leave your account unprotected.

Two-factor Authentication (2FA) helps prevent unauthorized access and protects your Omise account from misuse.

We strongly recommend enabling it now to keep your account secure.

Create, retrieve, update, and delete customers. When unused token identifiers are added to customers, they are saved as cards which can be used for repeated purchases.

Attributes

Name	Type	Description
object	string	The string `customer`.
id	string	The customer identifier matching `/cust(_test)?_[0-9a-z]+/`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) customer.
location	string	API path to retrieve the current `customer` object.
cards	list	List of cards belonging to the customer.
created_at	string	UTC datetime of customer creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
default_card	object_id_expandable	Identifier of default card for creating charges. Initially, value is first card assigned to a customer. If default card is deleted, the latest card added will be set as default. `null` if no cards.
deleted	boolean	Whether customer is deleted.
description	string	Customer description.
email	string	Customer email address. Used when the customer's email is not supplied during token creation.
linked_accounts	list	List of accounts linked for direct debit.
metadata	object	Custom metadata (e.g. {answer: 42}) for a customer. The maximum field length is 15.000 characters.

Example

JSON Response

{
  "object": "customer",
  "id": "cust_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/customers/cust_test_no1t4tnemucod0e51mo",
  "deleted": false,
  "metadata": {},
  "cards": {
    "object": "list",
    "data": [
      {
        "object": "card",
        "id": "card_test_no1t4tnemucod0e51mo",
        "livemode": false,
        "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards/card_test_no1t4tnemucod0e51mo",
        "deleted": false,
        "street1": "1448/4 Praditmanutham Road",
        "street2": null,
        "city": "Bangkok",
        "state": null,
        "phone_number": "0123456789",
        "postal_code": "10320",
        "country": "th",
        "financing": "credit",
        "bank": "Bank of the Unbanked",
        "brand": "Visa",
        "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
        "first_digits": null,
        "last_digits": "4242",
        "name": "Somchai Prasert",
        "expiration_month": 12,
        "expiration_year": 2024,
        "security_code_check": true,
        "tokenization_method": null,
        "created_at": "2019-12-31T12:59:59Z"
      }
    ],
    "limit": 20,
    "offset": 0,
    "total": 1,
    "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-12-31T12:59:59Z"
  },
  "default_card": "card_test_no1t4tnemucod0e51mo",
  "description": "Additional information about Somchai Prasert",
  "email": "somchai.prasert@example.com",
  "created_at": "2019-12-31T12:59:59Z"
}

Create a customer (and card)

- POST https://api.omise.co/customers

Creates and returns a new customer. This endpoint can also create a new card if an unused token is provided for the card parameter.

Request Parameters

Name	Type	Description
card	string	(optional) An unused token identifier to add as a new card to the customer.
description	string	(optional, but recommended) Description for a customer. Supplying any additional details about the customer helps Omise conduct fraud analysis better.
email	string	(optional, but recommended) Email address for the customer. Supplying the customer's email address helps Omise conduct fraud analysis better.
linked_account	string	(optional) The account that is linked for direct debit.
metadata	object	(optional) Custom metadata (e.g. {answer: 42}) for a customer. The maximum field length is 15.000 characters.

Example

Create a customer while attaching a card

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY: \
  -d "description=Additional information about Somchai Prasert." \
  -d "email=somchai.prasert@example.com" \
  -d "card=tokn_test_5g5mep9yrko3vx2f0hx"

<?php

$customer = OmiseCustomer::create(array(
  'email' => 'john.doe@example.com',
  'description' => 'John Doe (id: 30)',
  'card' => 'tokn_test_4xs9408a642a1htto8z'
));

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

const customer = await omise.customers.create({
  description: 'John Doe (id: 34)',
  email: 'john.doe@example.com',
  card: 'tokn_test_no1t4tnemucod0e51mo',
});
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.create({
  email: "john.doe@example.com",
  description: "John Doe (id: 30)",
  card: "tokn_test_4xs9408a642a1htto8z"
})

var token = await RetrieveToken();
var customer = await Client.Customers.Create(new CreateCustomerRequest
{
    Email = "john.doe@example.com",
    Description = "John Doe (id: 30)",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 30 }
    },
    Card = token.Id,
});

Console.WriteLine($"created customer: {customer.Id}");

Request<Customer> request = new Customer.CreateRequestBuilder()
        .email("john.doe@omise.co")
        .description("This cool customer!")
        .card("tokn_test_4xs9408a642a1htto8z")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Created customer: %s", customer.getId());

import omise

customer = omise.Customer.create(
    email="john.doe@example.com",
    description="John Doe (id: 30)",
    card="tokn_test_no1t4tnemucod0e51mo",
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.CreateCustomer{
	Email:       "john.doe@example.com",
	Description: "John Doe (id: 30)",
	Card:        "tokn_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.create(
  email:       "john.doe@example.com",
  description: "John Doe (id: 30)",
  card:        "tokn_test_4xs9408a642a1htto8z"
)

Create a customer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY: \
  -d "description=Additional information about Somchai Prasert." \
  -d "email=somchai.prasert@example.com"

<?php

$customer = OmiseCustomer::create(array(
  'email' => 'john.doe@example.com',
  'description' => 'John Doe (id: 30)'
));

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

const customer = await omise.customers.create({
  description: 'John Doe (id: 34)',
  email: 'john.doe@example.com',
});
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.create({
  email: "john.doe@example.com",
  description: "John Doe (id: 30)"
})

var customer = await Client.Customers.Create(new CreateCustomerRequest
{
    Email = "john.doe@example.com",
    Description = "John Doe (id: 30)",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 30 }
    }
});

Console.WriteLine($"created customer: {customer.Id}");

Request<Customer> request = new Customer.CreateRequestBuilder()
        .email("john.doe@omise.co")
        .description("This cool customer!")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Created customer: %s", customer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.create(
    email="john.doe@example.com", description="John Doe (id: 30)"
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.CreateCustomer{
	Email:       "john.doe@example.com",
	Description: "John Doe (id: 30)",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.create(
  email:       "john.doe@example.com",
  description: "John Doe (id: 30)"
)

Destroy a customer

- DELETE https://api.omise.co/customers/{id}

Destroys the customer matching :id.

Example

Destroy a customer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->destroy();
$customer->isDestroyed(); # => true

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

const customer = await omise.customers.destroy('cust_test_no1t4tnemucod0e51mo');
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.destroy
customer.destroyed? # => true

var customer = RetrieveCustomer();
customer = await Client.Customers.Destroy(customer.Id);
Console.WriteLine($"destroy customer: {customer.Id}");

Request<Customer> request = new Customer.DeleteRequestBuilder("cust_test_4xtrb759599jsxlhkrb").build();
Customer customer = client().sendRequest(request);

System.out.printf("Destroy customer: %s", customer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.destroy()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Deletion{}
err := client.Do(result, &operations.DestroyCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.destroy("cust_test_4xtrb759599jsxlhkrb")

List customers

- GET https://api.omise.co/customers

Returns a list of customers belonging to your account.

Request Parameters

Name	Type	Description
from	string	(optional, default: `1970-01-01T00:00:00Z`) Earliest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
limit	integer	(optional, default: `20`) Number of records returned.
offset	integer	(optional, default: `0`) Offset of the first record returned (i.e. how many records to skip from the beginning).
order	string	(optional, default: `chronological`, one of: `chronological`, `reverse_chronological`) Order of records returned.
to	string	(optional) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all customers

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY:

$customer = OmiseCustomer::retrieve();

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

const customer = await omise.customers.list();
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customers = Omise::Customer.list

var customers = await Client.Customers.GetList(order: Ordering.Chronological);
Console.WriteLine($"total customers: {customers.Total}");

Request<ScopedList<Customer>> request = new Customer.ListRequestBuilder().build();
ScopedList<Customer> customers = client().sendRequest(request);

System.out.printf("Total no. of customers: %d", customers.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customers = omise.Customer.retrieve()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.CustomerList{}
err := client.Do(result, &operations.ListCustomers{
	operations.List{
		From:  time.Now().Add(-1 * time.Hour),
		Limit: 100,
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.list

Retrieve a customer

- GET https://api.omise.co/customers/{id}

Returns the customer matching :id.

Example

Retrieve a customer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');

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

const customer = await omise.customers.retrieve('cust_test_no1t4tnemucod0e51mo');
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Get(customerId);
Console.WriteLine($"customer's email: {customer.Email}");

Request<Customer> request = new Customer.GetRequestBuilder("cust_test_4xtrb759599jsxlhkrb").build();
Customer customer = client().sendRequest(request);

System.out.printf("Customer email: %s", customer.getEmail());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.ScheduleList{}
err := client.Do(result, &operations.RetrieveCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")

Update a customer

- PATCH https://api.omise.co/customers/{id}

Updates and returns the updated customer matching :id.

Request Parameters

Name	Type	Description
card	string	(optional) An unused token identifier to add as a new card to the customer.
default_card	string	(optional) Identifier of the default card for creating charges.
description	string	(optional, but recommended) Description for a customer. Supplying any additional details about the customer helps Omise conduct fraud analysis better.
email	string	(optional, but recommended) Email address for the customer. Supplying the customer's email address helps Omise conduct fraud analysis better.
linked_account	string	(optional) The account that is linked for direct debit.
metadata	object	(optional) Custom metadata (e.g. {answer: 42}) for a customer. The maximum field length is 15.000 characters.

Example

Attach a card to a customer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "card=tokn_test_5g5mep9yrko3vx2f0hx"

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->update(array(
  'card' => 'tokn_test_4xs9408a642a1htto8z'
));

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

const customer = await omise.customers.update(
  'cust_test_no1t4tnemucod0e51mo',
  { card: 'tokn_test_no1t4tnemucod0e51mo' },
);
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.update(card: "tokn_test_4xs9408a642a1htto8z")

var token = await RetrieveToken();

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Update(customerId, new UpdateCustomerRequest
{
    Card = token.Id
});

Console.WriteLine($"updated customer: {customer.Id}");

Request<Customer> request = new Customer.UpdateRequestBuilder("cust_test_4xtrb759599jsxlhkrb")
        .card("tokn_test_4xs9408a642a1htto8z")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Updated customer: %s", customer.getId());

import omise

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.update(card="tokn_test_no1t4tnemucod0e51mo")

# alteratively
# customer.card = "tokn_test_no1t4tnemucod0e51mo"
# customer.update()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.UpdateCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
	Card:       "tokn_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.update("cust_test_4xtrb759599jsxlhkrb", [
  card: "tokn_test_4xs9408a642a1htto8z",
])

Update customer default card

curl
node.js

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "default_card=card_test_5g021zls9ei5suyryss"

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

const customer = await omise.customers.update(
    'cust_test_no1t4tnemucod0e51mo',
    { default_card: 'card_test_no1t4tnemucod0e51mo' }
);
console.log(customer);

Update customer email and description

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "email=somchai.prasert@example.com" \
  -d "description=Another description"

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->update(array(
  'email' => 'john.smith@example.com',
  'description' => 'Another description'
));

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

const customer = await omise.customers.update(
  'cust_test_no1t4tnemucod0e51mo',
  {
    email: 'john.smith@example.com',
    description: 'Gold card customer',
  },
);
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.update({
  email: "john.smith@example.com",
  description: "Another description"
})

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Update(customerId, new UpdateCustomerRequest
{
    Email = "john.smith@example.com",
    Description = "John Smith",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 99 }
    }
});

Console.WriteLine($"updated customer: {customer.Id}");

Request<Customer> request = new Customer.UpdateRequestBuilder("cust_test_4xtrb759599jsxlhkrb")
        .email("another@email.com")
        .description("Another description")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Updated email: %s", customer.getEmail());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.update(email="somchai.prasert@example.com", description="Another description")

# Or alternatively:
customer.email = "somchai.prasert@example.com"
customer.description = "Another description"
customer.update()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.UpdateCustomer{
	CustomerID:  "cust_test_no1t4tnemucod0e51mo",
	Email:       "john.smith@example.com",
	Description: "Another Description",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.update("cust_test_4xtrb759599jsxlhkrb", [
  email:       "john.smith@example.com",
  description: "Another description",
])