Create Customer

POST /customers

cURL

Customer (full data)

curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "merchant_customer_id": "4321",
  "merchant_customer_created_at": "2022-05-09T20:46:54.786342Z",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[e-mail]",
  "gender": "M",
  "date_of_birth": "1990-02-28",
  "nationality": "US",
  "country": "US",
  "document": {
    "document_type": "SSN",
    "document_number": "123-45-6789"
  },
  "phone": {
    "number": "5551234567",
    "country_code": "1"
  },
  "billing_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "state": "NY",
    "city": "New York",
    "zip_code": "10001",
    "neighborhood": "Manhattan"
  },
  "shipping_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "state": "NY",
    "city": "New York",
    "zip_code": "10001",
    "neighborhood": "Manhattan"
  },
  "metadata": [
    {
      "key": "ID",
      "value": "123456"
    }
  ]
}
'

201

Customer (full data)

{
  "id": "bf64527c-5531-4ece-bf2c-51a8e775d8e1",
  "merchant_customer_id": "AAAAAAAAAAAAAA0002",
  "first_name": "John",
  "last_name": "Doe",
  "gender": "M",
  "date_of_birth": "1990-02-28",
  "email": "[e-mail]",
  "nationality": "US",
  "country": "US",
  "document": {
    "document_type": "SSN",
    "document_number": "123-45-6789"
  },
  "phone": {
    "number": "5551234567",
    "country_code": "1"
  },
  "billing_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "state": "NY",
    "city": "New York",
    "zip_code": "10001",
    "neighborhood": "Manhattan"
  },
  "shipping_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "state": "NY",
    "city": "New York",
    "zip_code": "10001",
    "neighborhood": "Manhattan"
  },
  "metadata": [
    {
      "key": "ID",
      "value": "123456"
    }
  ],
  "created_at": "2025-04-24T18:54:54.351969Z",
  "updated_at": "2025-04-24T18:54:54.351971Z",
  "merchant_customer_created_at": "2022-05-09T20:46:54.786342Z"
}

This request creates a customer resource. You need to provide several parameters of the customer in the request body, including the unique identifier of the customer in the external merchant, personal information, as well as billing and shipping addresses.

Creating a customer generates a customer id that can be used to initialize the checkout.

Important

There are certain objects that are not mandatory when creating a “Customer”. However the more information you provide, the approval, conversion and fraud prevention rates will be positively impacted.

Authorizations

public-api-key · string · header · default: <Your public-api-key> · required

private-secret-key · string · header · default: <Your private-secret-key> · required

Body

application/json

merchant_customer_id · string · required

The unique identifier of the customer in the external merchant (MAX 255; MIN 3).

merchant_customer_created_at · string<date-time>

Customer's registration date on the merchants platform (MAX 27; MIN 27; ISO 8601)

first_name · string

The customer's first name (MAX 255; MIN 3).

last_name · string

The customer's last name (MAX 255; MIN 3).

gender · string

The customer's gender.

date_of_birth · string

The customer's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).

email · string

The customer's e-mail (MAX 255; MIN 3).

nationality · enum<string>

The customer's nationality (MAX 2; MIN 2; ISO 3166-1 [blocked]).

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SZ, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

country · enum<string>

The customer's country (MAX 2; MIN 2; ISO 3166-1 [blocked]).

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SZ, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW

document · object

Specifies the customer's document object, including its number and type. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

Show child attributes

phone · object

Specifies the customer's phone number object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

Show child attributes

billing_address · object

Specifies the customer's billing address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

Show child attributes

shipping_address · object

Specifies the customer's shipping address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

Show child attributes

metadata · object[]

Specifies a list of metadata objects. You can add up to 50 metadata objects.

Show child attributes

Response

201

application/json

201

Customer (full data)

Customer (min. data)

id · string

Example:

"bf64527c-5531-4ece-bf2c-51a8e775d8e1"

merchant_customer_id · string

Example:

"AAAAAAAAAAAAAA0002"

first_name · string

Example:

"John"

last_name · string

Example:

"Doe"

gender · string

Example:

"M"

date_of_birth · string

Example:

"1990-02-28"

email · string

Example:

"[e-mail]"

nationality · string

Example:

"US"

country · string

Example:

"US"

document · object

Show child attributes

phone · object

Show child attributes

billing_address · object

Show child attributes

shipping_address · object

Show child attributes

metadata · object[]

Show child attributes

created_at · string

Example:

"2025-04-24T18:54:54.351969Z"

updated_at · string

Example:

"2025-04-24T18:54:54.351971Z"

merchant_customer_created_at · string

Example:

"2022-05-09T20:46:54.786342Z"