Paloma Customers API

Updated: 15.10.2020 12:19

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. 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.

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

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