Checkout.com API logo

Customers

Create a customer

Store a customer's details in a customer object to reuse in future payments. When creating a customer, you can link payment instruments – the customer id returned can be passed as a source when making a payment.

NOTE: Specify a default instrument, otherwise the instruments array will not be saved on creation.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

The customer's email address

name
string <= 255 characters

The customer's name

object

The customer's phone number

metadata
object

Allows you to store additional information about a customer. You can include a maximum of 10 key-value pairs. Each key and value can be up to 100 characters long.

default
string

The ID of the instrument you want to set as this customer's default instrument

Responses
201

Customer created successfully

401

Unauthorized

422

Invalid data was sent

500

Internal Error

post/customers
Request samples
application/json
{
  • "email": "brucewayne@gmail.com",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu"
}
Response samples
application/json
{
  • "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
}

Get customer details

Returns the details of a customer and their payment instruments.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
required
string or string

The customer's ID or email

Responses
200

Customer retrieved successfully

401

Unauthorized

404

Customer not found

get/customers/{identifier}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Customers;

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    CustomerDetailsResponse response = await api.CustomersClient().Get("customer_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  • "email": "brucewayne@gmail.com",
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "instruments": [
    ]
}

Update customer details

Update the details of a customer and link payment instruments to them.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
identifier
required
string^(cus)_(\w{26})$

The customer's ID

Request Body schema: application/json
required
email
string <email> <= 255 characters

The email address of the customer

name
string <= 255 characters

The name of the customer

object

The customer's phone number

metadata
object

Allows you to store additional information about a customer. You can include a maximum of 10 key-value pairs. Each key and value can be up to 100 characters long. Providing metadata in this request will replace any existing stored for this customer.

default
string

The ID of this customer's default instrument

Responses
204

Customer updated successfully

401

Unauthorized

404

Customer not found

422

Invalid data was sent

patch/customers/{identifier}
Request samples
application/json
{
  • "email": "brucewayne@gmail.com",
  • "name": "Bruce Wayne",
  • "phone": {
    },
  • "metadata": {
    },
  • "default": "src_wmlfc3zyhqzehihu7giusaaawu"
}
Response samples
application/json
{
  • "request_id": "0HL80RJLS76I7",
  • "error_type": "request_invalid",
  • "error_codes": [
    ]
}

Delete a customer

Delete a customer and all of their linked payment instruments.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
identifier
required
string^(cus)_(\w{26})$

The customer's ID

Responses
204

Customer deleted successfully

401

Unauthorized

404

Customer not found or not associated with client

delete/customers/{identifier}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net

//API keys
ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

//OAuth
ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Vault)
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    EmptyResponse response = await api.CustomersClient().Delete("customer_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
➔ Next to Forward