Paloma Customers API
Updated: 15.10.2020 12:19
The Paloma Customers API defines endpoints for customers, users and orders operations.
https://[organization].paloma.one/api/customers/v2
Customers and Users
The Paloma Customers component distinguishes between customers and users. A Customer
being the person or entity that has a busines relationship with the shop operator and the User
being the person or entity
that is using the shop.
Each user is assigned to a customer. For B2C shops, Paloma assumes a 1:1 relation between a user and a customer by default. For B2B shops, a n:1 relation is common.
Creating a Customer
Create a new customer and user account. The email address will be used as identifier within the channel.
POST /{channel}/customers
{
"emailAddress": "hans.muster@astina.io",
"firstName": "Hans",
"lastName": "Muster",
"user": {
"password": "banana"
},
"locale": "de_DE"
}
User Authentication
After a customer is registered, we can use the authentication method.
POST /{channel}/users/authenticate
{
"username": "hans.muster@astina.io",
"password": "banana"
}
The return value is an authentication token:
{
"user": {
"username": "hans.muster@astina.io",
"id": "12324-3434-3434"
},
"customer": {
"customerNumber": "10001",
"emailAddress": "hans.muster@astina.io",
"locale": "de_DE",
"firstName": "Hans",
"lastName": "Muster",
"id": "43435-6565-6565",
...
}
}
If authentication is successful, your application is supposed to keep the returned authentication token in session. If you use a framework that provides a security component (e.g. PHP/Symfony), it is advised to integrate this API call with your security component.
Changing the User's Password
To change a user's password, the "Update password" operation can be used.
PUT /{channel}/users/{userId}/password
{
"currentPassword": "banana",
"newPassword": "pineapple"
}
If the user cannot provide the current password, the "Password reset" process can be used.
Start the password reset by providing the user's email address and a confirmationBaseUrl
.
POST /{channel}/users/password-reset
{
"emailAddress": "hans.muster@astina.io",
"confirmationBaseUrl": "https://mywebshop.com/security/password-reset"
}
The confirmationBaseUrl
needs to contain a link to your shop front-ends password reset view. A confirmation token will be appended to this URL to be included in the confirmation email sent to the user
(e.g. https://mywebshop.com/security/password-reset?token=YZCgyBXCkk9...
).
Once the user hase received the confirmation email and clicked on the link, the shop front-end should provide him with a form where the user can enter the new password.
After that, you can use the new password with the token to change the user's password.
PUT /{channel}/users/password-reset/{token}/password
{
"password": "pineapple"
}
Customer Addresses
Each customer has a list of addresses. The Customer API CRUD methods to manage those addresses. Each CustomerAddress has a type: contact
, billing
or shipping
. This type shows the purpose for which the address is normally used. The defaultAddress
property shows which address is set as the default address for each type.
GET /{channel}/customers/{customerId}/addressbook
See the Customers API Reference for details.
All customer addresses also come with a unique ID which can be used in the Checkout API to set the billing and shipping address (instead of passing a whole address object). See the Checkout API Reference for details.
Order History
Purchased orders for a customer can be accessed using the "List customer orders" operation.
GET /{channel}/{locale}/customers/{customerId}/orders
This returns a paginated list of the customer's orders, sorted by orderDate
in descending order by default.
{
"content": [
{
"id": "12345678-9012-3456-7890-123456789012",
"orderNumber": "123",
"channel": "CH",
"orderDate": "2018-03-14T10:07:26.000+0000",
"locale": "de_CH",
"status": "shipped"
"items": [
...
],
...
],
"totalPages": 1,
"totalElements": 2,
"last": true,
"first": true,
"size": 20,
"number": 0
}
See the CustomersOrders
model for more information.
Payment Instruments
Payment instruments for a customer can be accessed using the "List payment instruments" operation.
GET /{channel}/{locale}/customers/{customerId}/payment-instruments
This returns a list of customers' payment instruments.
[
{
"id": "01E4V2JCC9T33QXEAXPHCJEC4F",
"type": "Mastercard",
"maskedCardNumber": "513659xxxxxx5354",
"expirationMonth": "12",
"expirationYear": "24",
"expired": false
},
{
"id": "01F5V2JD49T33ZTEQXPVCJZC08",
"type": "VISA",
"maskedCardNumber": "476325xxxxxx7800",
"expirationMonth": "05",
"expirationYear": "19",
"expired": true
}
]
A payment instrument can be removed using the "Delete payment instrument" operation.
DELETE /{channel}/{locale}/customers/{customerId}/payment-instruments/{paymentInstrumentId}
Next: API Model Reference