Customer API

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	object_id	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	datetime	UTC datetime of customer creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
default_card	object_id	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.
metadata	object	Custom metadata (e.g. `{"answer": 42}`) for customer.

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
description	string	(optional, but recommended) Description for customer. Supplying any additional details about the customer helps Omise better conduct fraud analysis.
email	string	(optional, but recommended) Email address for customer. Supplying the customer's email address helps Omise better conduct fraud analysis.
card	object_id	(optional) An unused token identifier to add as a new card to the customer. Does not support a token created from a card that has already been tokenized.
metadata	object	(optional) Custom metadata (e.g. `{"answer": 42}`) for customer.

Example

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)"
)

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"
)

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
description	string	(optional, but recommended) Description for customer. Supplying any additional details about the customer helps Omise better conduct fraud analysis.
email	string	(optional, but recommended) Email address for customer. Supplying the customer's email address helps Omise better conduct fraud analysis.
card	object_id	(optional) An unused token identifier to add as a new card to the customer. Does not support a token created from a card that has already been tokenized.
default_card	object_id	(optional) Identifier of the default card for creating charges.
metadata	object	(optional) Custom metadata (e.g. `{"answer": 42}`) for customer.

Example

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",
])

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);

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",
])

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")

JSON Response

JSON

{
  "object": "customer",
  "id": "cust_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/customers/cust_test_no1t4tnemucod0e51mo",
  "created_at": "2019-07-23T01:19:25Z",
  "deleted": true,
  "default_card": null,
  "email": null,
  "description": null,
  "metadata": {
  },
  "cards": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-07-23T01:19:25Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards",
    "data": [

    ]
  }
}

List customers

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

Returns a list of customers belonging to your account.

Request Parameters

Name	Type	Description
from	datetime	(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, maximum: 100) 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`) Order of records returned. One of `chronological` (earliest to latest) or `reverse_chronological` (latest to earliest).
to	datetime	(optional, default: current UTC datetime) 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

List schedules

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

Returns a list of schedules belonging to customer matching :id.

Request Parameters

Name	Type	Description
from	datetime	(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, maximum: 100) 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`) Order of records returned. One of `chronological` (earliest to latest) or `reverse_chronological` (latest to earliest).
to	datetime	(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all charge schedules for a customer

curl
node.js
go

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

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

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

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

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