Paloma Customers API

Updated: 23.04.2020 13:36

The Paloma Customers API defines endpoints for customers, users and orders operations.

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. By default, Paloma assumes a 1:1 relation between a user and a customer. If your project requires multiple users for a single customer, please contact us.

• Customers API Reference for customer operations

• Customers API Reference for user operations

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

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