Customer API

The Customer API allows you to create, retrieve, update, and delete customers. Customers represent entities that have zero or more saved cards which can be used for repeated purchases.

Attribute

Name Type Description
object string

The string customer.

id object_id

The CUSTOMER_ID 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 datetime

UTC datetime of the creation of the customer in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

default_card object_id

CARD_ID of default card for creating charges. Initially the first card assigned to a customer. If destroyed, latest added card will be set as default. null if no cards.

deleted boolean

Whether customer is deleted.

description string

Description of the customer.

email string

Email address associated with the customer.

metadata object

Custom metadata (e.g. {"customer-id": 42}) for customer.

Example

  • Json Response

List all customers

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

Returns a list of all customer objects belonging to your account.

Request Parameter

Name Type Description
offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) Order in which to return records. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all customers

Create a customer

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

Returns a new customer object

Request Parameter

Name Type Description
email string

(optional) Email to attach to the customer.

description string

(optional) Description to attach to the customer.

metadata object

(optional) Custom metadata (e.g. {"customer-id": 42}) to attach to the customer.

card object_id

(optional) An unused TOKEN_ID to add as a new card to the customer.

Example

  • Create a customer

  • Create a customer and attach a card

Retrieve a customer

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

Returns an existing customer object

Example

  • Retrieve a customer

Update a customer

- PATCH https://api.omise.co/customers/CUSTOMER_ID

Returns the updated customer object

Request Parameter

Name Type Description
email string

(optional) Email to attach to the customer.

description string

(optional) Description to attach to the customer.

metadata object

(optional) Custom metadata (e.g. {"customer-id": 42}) to attach to the customer.

default_card object_id

(optional) A CARD_ID to set as the default. Must already belong to the customer.

card object_id

(optional) An unused TOKEN_ID to add as a new card to the customer.

Example

  • Update a customer email, description, and default card

  • Attach a card to a customer

Destroy a customer

- DELETE https://api.omise.co/customers/CUSTOMER_ID

Returns the destroyed customer object

Example

  • Destroy a customer

  • Response (JSON)