> ## Documentation Index
> Fetch the complete documentation index at: https://yuno-3979e326-fix-create-subscription-card-usage.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Customer
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.
## OpenAPI
````yaml /openapi/customers/create-customer.json POST /customers
openapi: 3.1.0
info:
title: customer-api
version: 1.0.2
servers:
- url: https://api-sandbox.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/customers:
post:
summary: Create Customer
operationId: create-customer
requestBody:
content:
application/json:
schema:
type: object
required:
- merchant_customer_id
properties:
merchant_customer_id:
type: string
description: >-
The unique identifier of the customer in the external
merchant (MAX 255; MIN 3).
merchant_customer_created_at:
type: string
description: >-
Customer's registration date on the merchants platform (MAX
27; MIN 27; [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601))
format: date-time
first_name:
type: string
description: The customer's first name (MAX 255; MIN 3).
last_name:
type: string
description: The customer's last name (MAX 255; MIN 3).
gender:
type: string
description: The customer's gender.
date_of_birth:
type: string
description: >-
The customer's date of birth in the YYYY-MM-DD format (MAX
10; MIN 10).
email:
type: string
description: The customer's e-mail (MAX 255; MIN 3).
nationality:
type: string
description: >-
The customer's nationality (MAX 2; MIN 2; [ISO
3166-1](country-reference)).
enum:
- 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:
type: string
description: >-
The customer's country (MAX 2; MIN 2; [ISO
3166-1](country-reference)).
enum:
- 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:
type: object
description: >-
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.
properties:
document_number:
type: string
description: >-
The customer's document number (MAX 40; MIN 3). This
field is required if the 'document' object is included
in the request.
document_type:
type: string
description: >-
The customer's document type (MAX 6, MIN 3; [Country
reference](country-reference)).
phone:
type: object
description: >-
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.
properties:
country_code:
type: string
description: >-
The country calling code of the customer's phone (MAX 3;
MIN 1). Possible values values: Check the [Country
reference.](country-reference) This field is required if
the 'phone' object is included in the request.
number:
type: string
description: >-
The customer's phone number, without the country code
(MAX 32; MIN 1). This field is required if the 'phone'
object is included in the request.
billing_address:
type: object
description: >-
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.
properties:
address_line_1:
type: string
description: >-
The primary billing address line of the customer (MAX
255; MIN 3). This field is required if the
'billing_address' object is included in the request.
address_line_2:
type: string
description: >-
The secondary billing address line of the customer (MAX
255; MIN 3).
building_number_1:
type: string
description: >-
The primary building number of the customer (MAX 255;
MIN 3)
building_number_2:
type: string
description: >-
The secondary building number of the customer (MAX 255;
MIN 3)
city:
type: string
description: >-
The city considered for the billing address (MAX 255;
MIN 3). This field is required if the 'billing_address'
object is included in the request.
country:
type: string
description: >-
The country considered for the billing address (MAX 2;
MIN 2; [ISO 3166-1](country-reference)). This field is
required if the 'billing_address' object is included in
the request.
enum:
- 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
state:
type: string
description: >-
The state considered for the billing address (MAX 255;
MIN 3).
zip_code:
type: string
description: >-
The zipcode considered for the billing address (MAX 10;
MIN 5).
neighborhood:
type: string
description: >-
The neighborhood of the address line of the customer
(MAX 255; MIN 1).
required:
- address_line_1
- city
shipping_address:
type: object
description: >-
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.
properties:
address_line_1:
type: string
description: >-
The primary shipping address line of the customer (MAX
255; MIN 3). This field is required if the
'shipping_address' object is included in the request.
address_line_2:
type: string
description: >-
The secondary shipping address line of the customer (MAX
255; MIN 3).
building_number_1:
type: string
description: >-
The primary building number of the customer (MAX 255;
MIN 3)
building_number_2:
type: string
description: >-
The secondary building number of the customer (MAX 255;
MIN 3)
city:
type: string
description: >-
The city considered for the shipping address (MAX 255;
MIN 3). This field is required if the 'shipping_address'
object is included in the request.
country:
type: string
description: >-
The country considered for the shipping address (MAX 2;
MIN 2; [ISO 3166-1](country-reference)). This field is
required if the 'shipping_address' object is included in
the request.
enum:
- 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
state:
type: string
description: >-
The state considered for the shipping address (MAX 255;
MIN 3).
zip_code:
type: string
description: >-
The zipcode considered for the shipping address (MAX 10;
MIN 5).
neighborhood:
type: string
description: >-
The neighborhood of the address line of the customer(MAX
255; MIN 1).
metadata:
type: array
description: >-
Specifies a list of metadata objects. You can add up to 50
metadata objects.
items:
properties:
key:
type: string
description: The metadata key (MAX 48).
value:
type: string
description: The metadata key value (MAX 512).
required:
- key
- value
type: object
examples:
Customer (full data):
value:
merchant_customer_id: '4321'
merchant_customer_created_at: '2022-05-09T20:46:54.786342Z'
first_name: John
last_name: Doe
email: john.doe@email.com
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'
Customer (min. data):
value:
merchant_customer_id: '4321'
first_name: John
last_name: Doe
email: john.doe@email.com
responses:
'201':
description: '201'
content:
application/json:
examples:
Customer (full data):
value:
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: john.doe@email.com
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'
Customer (min. data):
value:
id: fe17085f-e9fd-4882-a42a-21eacc10fbb6
merchant_customer_id: AAAAAAA000001
first_name: John
last_name: Doe
gender: null
date_of_birth: null
email: john.doe@email.com
nationality: null
country: null
document: null
phone: null
billing_address: null
shipping_address: null
created_at: '2025-04-24T18:54:15.805086Z'
updated_at: '2025-04-24T18:54:15.805088Z'
merchant_customer_created_at: null
schema:
oneOf:
- title: Customer (full data)
type: object
properties:
id:
type: string
example: bf64527c-5531-4ece-bf2c-51a8e775d8e1
merchant_customer_id:
type: string
example: AAAAAAAAAAAAAA0002
first_name:
type: string
example: John
last_name:
type: string
example: Doe
gender:
type: string
example: M
date_of_birth:
type: string
example: '1990-02-28'
email:
type: string
example: john.doe@email.com
nationality:
type: string
example: US
country:
type: string
example: US
document:
type: object
properties:
document_type:
type: string
example: SSN
document_number:
type: string
example: 123-45-6789
phone:
type: object
properties:
number:
type: string
example: '5551234567'
country_code:
type: string
example: '1'
billing_address:
type: object
properties:
address_line_1:
type: string
example: 123 Main St
address_line_2:
type: string
example: Apt 4B
country:
type: string
example: US
state:
type: string
example: NY
city:
type: string
example: New York
zip_code:
type: string
example: '10001'
neighborhood:
type: string
example: Manhattan
shipping_address:
type: object
properties:
address_line_1:
type: string
example: 123 Main St
address_line_2:
type: string
example: Apt 4B
country:
type: string
example: US
state:
type: string
example: NY
city:
type: string
example: New York
zip_code:
type: string
example: '10001'
neighborhood:
type: string
example: Manhattan
metadata:
type: array
items:
type: object
properties:
key:
type: string
example: ID
value:
type: string
example: '123456'
created_at:
type: string
example: '2025-04-24T18:54:54.351969Z'
updated_at:
type: string
example: '2025-04-24T18:54:54.351971Z'
merchant_customer_created_at:
type: string
example: '2022-05-09T20:46:54.786342Z'
- title: Customer (min. data)
type: object
properties:
id:
type: string
example: fe17085f-e9fd-4882-a42a-21eacc10fbb6
merchant_customer_id:
type: string
example: AAAAAAA000001
first_name:
type: string
example: John
last_name:
type: string
example: Doe
gender: {}
date_of_birth: {}
email:
type: string
example: john.doe@email.com
nationality: {}
country: {}
document: {}
phone: {}
billing_address: {}
shipping_address: {}
created_at:
type: string
example: '2025-04-24T18:54:15.805086Z'
updated_at:
type: string
example: '2025-04-24T18:54:15.805088Z'
merchant_customer_created_at: {}
'400':
description: '400'
content:
application/json:
examples:
Bad Request:
value:
code: INVALID_REQUEST
messages:
- Invalid request
schema:
type: object
properties:
code:
type: string
example: INVALID_REQUEST
messages:
type: array
items:
type: string
example: Invalid request
'401':
description: '401'
content:
application/json:
examples:
Unauthorized:
value:
code: INVALID_CREDENTIALS
messages:
- Invalid Credentials
schema:
type: object
properties:
code:
type: string
example: INVALID_CREDENTIALS
messages:
type: array
items:
type: string
example: Invalid Credentials
'403':
description: '403'
content:
application/json:
examples:
Forbidden:
value:
code: AUTHORIZATION_REQUIRED
messages:
- The merchant has no authorization to use this API
schema:
type: object
properties:
code:
type: string
example: AUTHORIZATION_REQUIRED
messages:
type: array
items:
type: string
example: The merchant has no authorization to use this API
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````