Skip to content
SumUp Developer

Retrieve a customer

SumUp API reference and code samples.

Customers

Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform.

Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.

The Customer object

Saved customer details.

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1 string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2 string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"
The Customer object
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Create a customer

Creates a new saved customer resource which you can later manipulate and save payment instruments to.

Required scopes: payment_instruments

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1 string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2 string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Response 400

Problem

  • type string uri required

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string uri

    A URI reference that identifies the specific occurrence of the problem.

Error Forbidden

  • error_message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • status_code string

    HTTP status code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

POST /v0.1/customers 
curl https://api.sumup.com/v0.1/customers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "customer_id": "831ff8d4cd5958ab5670"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.create({
  customer_id: "831ff8d4cd5958ab5670",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.CreateAsync(
    new Customer
    {
        CustomerId = "831ff8d4cd5958ab5670",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().createCustomer(
  Customer.builder()
    .customerId("831ff8d4cd5958ab5670")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.create(CreateCustomerBody(
  customer_id="831ff8d4cd5958ab5670",
))
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->create([
  'customer_id' => '831ff8d4cd5958ab5670',
]);
client := sumup.NewClient()


result, err := client.Customers.Create(context.Background(), sumup.CustomersCreateParams{
  CustomerId: "831ff8d4cd5958ab5670",
})
use sumup::Client;


let client = Client::default();


let result = client.customers().create(sumup::CreateCustomerBody{
  customer_id: "831ff8d4cd5958ab5670".to_string(),
}).await;
Create a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Retrieve a customer

Retrieves an identified saved customer resource through the unique customer_id parameter, generated upon customer creation.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Problem

  • type string uri required

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string uri

    A URI reference that identifies the specific occurrence of the problem.

Error Forbidden

  • error_message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • status_code string

    HTTP status code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

GET /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.get("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.GetAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().getCustomer(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.get("customer_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->get('customer_id');
client := sumup.NewClient()


result, err := client.Customers.Get(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().get("customer_id").await;
Retrieve a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Update a customer

Updates an identified saved customer resource's personal details.

The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Body Parameters

  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1 string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2 string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Problem

  • type string uri required

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string uri

    A URI reference that identifies the specific occurrence of the problem.

Error Forbidden

  • error_message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • status_code string

    HTTP status code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

PUT /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.update("customer_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.UpdateAsync(
    "customer_id",
    new UpdateCustomerBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().updateCustomer(
  "customer_id",
  UpdateCustomerBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.update("customer_id", UpdateCustomerBody(


))
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->update('customer_id', [


]);
client := sumup.NewClient()


result, err := client.Customers.Update(context.Background(), "customer_id", sumup.CustomersUpdateParams{


})
use sumup::Client;


let client = Client::default();


let result = client.customers().update("customer_id", sumup::UpdateCustomerBody{}).await;
Update a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

List payment instruments

Lists all payment instrument resources that are saved for an identified customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Problem

  • type string uri required

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string uri

    A URI reference that identifies the specific occurrence of the problem.

Error Forbidden

  • error_message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • status_code string

    HTTP status code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

GET /v0.1/customers/{customer_id}/payment-instruments 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.listPaymentInstruments("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.ListPaymentInstrumentsAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().listPaymentInstruments(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.list_payment_instruments("customer_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->listPaymentInstruments('customer_id');
client := sumup.NewClient()


result, err := client.Customers.ListPaymentInstruments(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().list_payment_instruments("customer_id").await;
List payment instruments response
[
  {
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "active": true,
    "type": "card",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MH4H92C7"
    },
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00"
  }
]
Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

  • token string required

    Unique token identifying the card saved as a payment instrument resource.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

Problem

  • type string uri required

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string uri

    A URI reference that identifies the specific occurrence of the problem.

Error Forbidden

  • error_message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • status_code string

    HTTP status code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

DELETE /v0.1/customers/{customer_id}/payment-instruments/{token} 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.deactivatePaymentInstrument("customer_id", "token");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.DeactivatePaymentInstrumentAsync(
    "customer_id",
    "token"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().deactivatePaymentInstrument(
  "customer_id",
  "token"
);
from sumup import Sumup


client = Sumup()


result = client.customers.deactivate_payment_instrument("customer_id", "token")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->deactivatePaymentInstrument('customer_id', 'token');
client := sumup.NewClient()


result, err := client.Customers.DeactivatePaymentInstrument(context.Background(), "customer_id", "token")
use sumup::Client;


let client = Client::default();


let result = client.customers().deactivate_payment_instrument("customer_id", "token").await;