GoCardlessDeveloper Docs
Create a sandbox account

Customer

View as Markdown

Customer objects hold the contact details for a customer. A customer can have several customer bank accounts, which in turn can have several Direct Debit mandates.

Create a customer#

POST/customers

Creates a new customer object.

POST https://api.gocardless.com/customers HTTP/1.1
Content-Type: application/json
{
  "customers": {
    "email": "user@example.com",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "city": "London",
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}
@client.customers.create(
  params: {
    email: "user@example.com",
    given_name: "Jacob",
    family_name: "Pargin",
    country_code: "GB"
  }
)
client.customers.create(params={
  "email": "user@example.com",
  "given_name": "Frank",
  "family_name": "Osborne",
  "address_line1": "27 Acer Road",
  "address_line2": "Apt 2",
  "city": "London",
  "postal_code": "E8 3GX",
  "country_code": "GB",
  "metadata": {
    "salesforce_id": "ABCD1234"
  }
})
const customer = await client.customers.create({
  email: "user@example.com",
  given_name: "Frank",
  family_name: "Osborne",
  address_line1: "27 Acer Road",
  address_line2: "Apt 2",
  city: "London",
  postal_code: "E8 3GX",
  country_code: "GB",
  metadata: {
    salesforce_id: "ABCD1234"
  }
});
$client->customers()->create([
  "params" => ["email" => "tim@gocardless.com",
               "given_name" => "Tim",
               "family_name" => "Rogers",
               "country_code" => "GB"]
]);
Customer customer = client.customers().create()
  .withEmail("user@example.com")
  .withGivenName("Frank")
  .withFamilyName("Osborne")
  .withAddressLine1("27 Acer Road")
  .withAddressLine2("Apt 2")
  .withCity("London")
  .withPostalCode("E8 3GX")
  .withCountryCode("GB")
  .withMetadata("salesforce_id", "ABCD1234")
  .execute();
customerCreateParams := gocardless.CustomerCreateParams{
  AddressLine1: "27 Acer Road",
  AddressLine2: "Apt 2",
  City:         "London",
  PostalCode:   "E8 3GX",
  CountryCode:  "GB",
  Email:        "user@example.com",
  GivenName:    "Frank",
  FamilyName:   "Osborne",
}

customer, err := client.Customers.Create(ctx, customerCreateParams)
var customerRequest = new GoCardless.Services.CustomerCreateRequest()
{
    Email = "user@example.com",
    GivenName = "Frank",
    FamilyName = "Osborne",
    AddressLine1 = "27 Acer Road",
    AddressLine2 = "Apt 2",
    City = "London",
    PostalCode = "E8 3GX",
    CountryCode = "GB",
    Metadata = new Dictionary<string, string>()
    {
      {"salesforce_id", "ABCD1234"}
    }
};

var customerResponse = await client.Customers.CreateAsync(customerRequest);
GoCardless.Resources.Customer customer = customerResponse.Customer;
Responsehttp
HTTP/1.1 201 Created
Location: /customers/CU123
Content-Type: application/json
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "user@example.com",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_identity_number": null,
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}
Request Body
customersobject
16 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 201

Resource created successfully

customersobject
18 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

List customers#

GET/customers

Returns a cursor-paginated list of your customers.

GET https://api.gocardless.com/customers?after=CU123 HTTP/1.1
@client.customers.list

@client.customers.list(
  params: {
    "created_at[gt]" => "2016-08-06T09:30:00Z"
  }
)

@client.customers.list.records.each { |customer| puts customer.inspect }
client.customers.list().records

client.customers.list(params={"after": "CU123"}).records
const customer = await client.customers.list();

// List customers with a given currency.
await client.customers.list({ currency: "GBP" });
$client->customers()->list();

$client->customers()->list([
  "params" => ["created_at[gt]" => "2015-11-03T09:30:00Z"]
]);
for (Customer customer : client.customers().all().execute()) {
  System.out.println(customer.getId());
}
customerListParams := gocardless.CustomerListParams{
  Currency: "GBP",
}

customerListResult, err := client.Customers.List(ctx, customerListParams)
for _, customer := range customerListResult.Customers {
    fmt.Println(customer.GivenName)
}
var customerListResponse = client.Customers.All();
foreach (GoCardless.Resources.Customer customer in customerListResponse)
{
    Console.WriteLine(customer.GivenName);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": "CU000",
      "after": "CU456"
    },
    "limit": 50
  },
  "customers": [{
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "user@example.com",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }]
}
Response 200

Successful response

customersarray
18 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single customer#

GET/customers/{customer_id}

Retrieves the details of an existing customer.

Path Parameters

NameTypeDescription
customer_idrequiredstring

The customer id

GET https://api.gocardless.com/customers/CU123 HTTP/1.1
@client.customers.get("CU123")
client.customers.get("CU123")
const customer = await client.customers.find("CU123");
$client->customers()->get("CU123");
Customer customer = client.customers().get("CU123").execute();
customer, err := client.Customers.Get(ctx, "CU123")
var customerResponse = await client.Customers.GetAsync("CU0123");
GoCardless.Resources.Customer customer = customerResponse.Customer;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "user@example.com",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "27 Acer Road",
    "address_line2": "Apt 2",
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_identity_number": null,
    "metadata": {
      "salesforce_id": "ABCD1234"
    }
  }
}

GET https://api.gocardless.com/customers/CU123 HTTP/1.1

HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}
Response 200

Successful response

customersobject
18 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Update a customer#

PUT/customers/{customer_id}

Updates a customer object. Supports all of the fields supported when creating a customer.

Path Parameters

NameTypeDescription
customer_idrequiredstring

The customer id

PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
Content-Type: application/json
{
  "customers": {
    "email": "updated_user@example.com",
    "given_name": "Jenny",
    "family_name": "Osborne",
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}
@client.customers.update(
  "CU123",
  params: {
    metadata: { custom_reference: "EXAMPLELTD01" }
  }
)
client.customers.update("CU123", params={
  "email": "updated_user@example.com"
})
const customer = await client.customers.update(
  "CU123",
  {
    email: "updated_user@example.com",
  }
);
$client->customers()->update("CU123", [
  "params" => ["email" => "tim@gocardless.com"]
]);
client.customers().update("CU123")
  .withEmail("updated_user@example.com")
  .withGivenName("Jenny")
  .execute();
customerUpdateParams := gocardless.CustomerUpdateParams{
  Email: "updated_user@example.com",
}

customer, err := client.Customers.Update(ctx, "CU123", customerUpdateParams)
var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"custom_reference", "NEWREFERENCE001"}
    }
};
var customerResponse = await client.Customers.UpdateAsync("CU0123", customerRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "customers": {
    "id": "CU123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "email": "updated_user@example.com",
    "given_name": "Frank",
    "family_name": "Osborne",
    "address_line1": "29 Acer Road",
    "address_line2": "Apt 3",
    "address_line3": "Block 4",
    "city": "London",
    "region": null,
    "postal_code": "E8 3GX",
    "country_code": "GB",
    "language": "en",
    "phone_number": null,
    "swedish_identity_number": null,
    "danish_identity_number": null,
    "metadata": {
      "salesforce_id": "EFGH5678"
    }
  }
}

PUT https://api.gocardless.com/customers/CU123 HTTP/1.1

HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}
Request Body
customersobject
16 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 200

Successful response

customersobject
18 properties
idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Remove a customer#

DELETE/customers/{customer_id}

Removed customers will not appear in search results or lists of customers (in our API or exports), and it will not be possible to load an individually removed customer by ID.

The action of removing a customer cannot be reversed, so please use with care.

Path Parameters

NameTypeDescription
customer_idrequiredstring

The customer id

DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1
@client.customers.remove("CU123")
client.customers.remove("CU123")
const customer = await client.customers.remove("CU123");
$client->customers()->remove("CU123");
client.customers().remove("CU123").execute();
customer, err := client.Customers.Remove(ctx, "CU123", gocardless.CustomerRemoveParams{})
await client.Customers.RemoveAsync("CU0123");
Responsehttp
HTTP/1.1 204 No Content

DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1

HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": {
    "documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
    "message": "This customer data has been removed",
    "type": "invalid_api_usage",
    "errors": [
      {
        "reason": "customer_removed",
        "message": "This customer data has been removed"
      }
    ],
    "code": 410,
    "request_id": "deadbeef-0000-4000-0000-444400004444"
  }
}
Request Body
customersobject
Response 204

Resource deleted successfully (no content)

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard