Create shopper details.

Create New Shopper

Creates an address including name for the shopper.

POST /ps/api/public/v1/merchants/{merchant_key}/shoppers


merchant_keyMerchantKeyThe key of the merchant.


Not applicable.


shopper_referenceString(1, 50)MThe shopper reference from the merchant.
nameBlockMThe shopper name for the address.
+ initialsString(1, 35)OThe initials. This field is commonly omitted.
+ firstString(1, 35)MThe first given name.
+ middleString(1, 35)OAny subsequent given name or names. May also be used as middle initial.
+ lastString(1, 35)MThe family or inherited name(s).
addressBlockMThe address details.
+ streetString(1, 100)MThe street.
+ housenumberString(1, 35)MThe house number.
+ housenumber_additionString(1, 35)OThe addition to the house number.
+ postal_codeString(1, 35)OThe postal or zip code.
+ cityString(1, 35)MThe city.
+ stateString(1, 40)CA state or province. Is mandatory for Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand and the USA when PayPal is used as payment method.
+ countryCountryMThe country as ISO 3166-1 Alpha 2.
emailString(1, 200)MThe email address of the shopper.
genderEnum(1)OThe gender of the shopper: "M" (Male), "F" (Female), or "U" (Unknown).
date_of_birthDateOThe date of birth of the shopper (yyyy-mm-dd).
phone_numberString(1, 50)OThe phone number of the shopper.

Note :

  • gender, date_of_birth and phone_number are only used for the payment methods Afterpay, Klarna, Giropay, ELV, E-Financing, and Capayable.
  • The address fields street, city and state can accept apostrophes at the beginning.


shopper_keyShopperKeyMThe key of the created or existing shopper.
address_keyAddressKeyMThe key of the created address.

HTTP Status

201 (Created)The order is successfully created.
400 (Bad Request)The request was not valid.
404 (Not Found)The merchant key was not found.

Create New shopper address example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \ \
    -d '{
        "shopper_reference" : "vk20170224p",
        "name" : {
             "first"  : "Johan",
             "middle" : "de",
             "last"   : "Vries"
        "address"   : {
             "street"      : "Hoofdstraat",
             "housenumber" : "82",
             "postalcode"  : "3972LB",
             "city"        : "Driebergen-Rijsenburg",
             "state"       : "Utrecht",
             "country"     : "DE"
        "email"         : "[email protected]",
        "gender"        : "M",
        "date_of_birth" : "1996-12-01",
        "phone_number"  : "+31611223344"
< Http 201 Created
<    '{
        "shopper_key" : "ec11cd24-e667-4f9e-a677-5ffe0d4aee5e",
        "address_key" : "ec11cd24-e667-4f9e-a677-5ffe0d4aee5e"

Note :

  • Currently, the same key is generated for shopper_key and address_key. In the future it will be different.