Create a customer

/v0.1/customers

Creates a customer using the customer_id you supply. Choose an identifier that maps to the payer in your own system and reuse it when retrieving the customer or associating checkouts and saved payment instruments with them.

OAuth scopes: Requires one of: payment_instruments, customers.write.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes payment_instrumentscustomers.write

Authorization guide

Body parameters

application/jsonrequired

Details of the customer.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsobject
Personal details for the customer.
Show 7 properties
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestring
  format: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstring
  maxLength: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressobject
  Profile's personal address information.
  
  Show 6 properties
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

Responses

201application/json

Returns the customer resource.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsobject
Personal details for the customer.
Show 7 properties
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestring
  format: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstring
  maxLength: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressobject
  Profile's personal address information.
  
  Show 6 properties
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

400application/json

The request body is invalid.

Exactly one of the following variants.

ErrorExtended

View ErrorExtended schema

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"
paramstring
Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.

Example: "card.name"

CustomerValidationError

View CustomerValidationError schema

instancestringrequired
Unique identifier of this error occurrence.

Example: "32a44c6c-85d3-49e8-86bf-a5bba98c4621"
error_codestringrequired
Platform code for the error.

Example: "INVALID"
error_messagestringrequired
Short description of the error.

Example: "customer_id"

401application/json

The request is not authorized.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

403application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

409application/json

A customer with the provided identifier already exists.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Code sample

curl --request POST \
  --url https://api.sumup.com/v0.1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  }
}
'

sumup customers create \
  --first-name "John" \
  --last-name "Doe" \
  --email "user@example.com" \
  --phone "+491635559723" \
  --tax-id "423.378.593-47" \
  --birth-date "1993-12-31" \
  --address-line-1 "Sample street" \
  --address-line-2 "ap. 5" \
  --address-city "Berlin" \
  --address-postal-code "10115" \
  --address-state "Berlin" \
  --address-country "DE"

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.customers.create(
    {
      "customer_id": "831ff8d4cd5958ab5670"
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Customers.CreateAsync(
            new Customer
            {
                CustomerId = "831ff8d4cd5958ab5670",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class CreateCustomerSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.customers().create(
            com.sumup.sdk.models.Customer.builder()
                .customerId("831ff8d4cd5958ab5670")
                .build()
        );
    System.out.println(result);
  }
}

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

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

$body = [
    'customer_id' => '831ff8d4cd5958ab5670',
];

$result = $sumup->customers()->create(
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Customers.Create(context.TODO(), sumup.CustomersCreateParams{
		CustomerID: "831ff8d4cd5958ab5670",
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::customers::CreateRequest::builder()
        .customer_id("831ff8d4cd5958ab5670")
        .build();
    let response = client.customers().create(body).await.expect("create request failed");
    println!("{response:#?}");
}

Response example

{
  "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"
    }
  }
}

{
  "error_code": "INVALID",
  "message": "Validation error",
  "param": "customer_id"
}

{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}

{
  "error_message": "request_not_allowed",
  "error_code": "FORBIDDEN",
  "status_code": "403"
}

{
  "message": "Customer already exists",
  "error_code": "CUSTOMER_ALREADY_EXISTS"
}