Customers API

Overview

Customers API makes it possible to find existing customers (both individual persons and organizations) using the loyalty card number or search criteria. This feature can be used to retrieve details of customers on a POS. The Customers API also enables the registration of new customers in the Customer service of Vynamic Engage.

Features

The GET /customers/card/{cardNumber} endpoint exposes the following details of a customer, which can be made available to the cashier on the POS system:

  • general customer details such as name, family name, date of birth
  • loyalty cards assigned to the customer and a list of loyalty programs that the customer is enrolled in
  • details of targeted/relevant offers assigned to the customer
  • details of all the stamps collected and redeemed by the customer
  • details of all the coupons collected and redeemed by the customer

The GET /customers endpoint enables searching for customers based on the following search criteria:

  • customer's name, date of birth, date of registration in the Customer service
  • customer's phone number, email address, physical address
  • customer's status in the Customer service (active, pending, inactive, marked for deletion)
  • customer's tax ID

The POST /customers endpoint enables registering new customers in the Customer service. In integration with DN's Vynamic Engage services, the cashier has a quick and easy way to populate a known customer's information on POS while issuing an invoice. This way the transaction can be completed quickly and the customer does not have to provide the same information during each visit.

The PUT /customers/{id} endpoint enables updating the customer records in the Customer Repository. The cashier can modify the customer details and use the updated data in customer invoices. The updated details appear on the fiscal document and are stored in the Customer Repository to reuse on future visits.

Example: A cashier issues a complete invoice. The customer informs that their address details have changed since the last visit and requests the cashier to modify the data. The cashier enters the new address and the fields are updated in the POS data entry form. The updated details appear on the fiscal document and are stored in Customer Repository.

The POST /customers/individualPersons/bulkImport endpoint enables the POS system to import customer data in bulk.

Additionally, the Customers API exposes the following endpoints related to customer accounts:

  • GET /accounts/search - Enables searching for an account by customerId or cardId.
  • POST /accounts/{id}/movements - Records a movement on the account (pay in, pay out, etc.).
  • GET /statements/{accountId} - Retrieves the account statement (a complete list of movements on the account).
  • GET /accounts/movementsForInvoice - Retrieves a list of transactions that require invoicing.
  • GET /accounts/{id}/invoices - Retrieves invoices associated with a specific customer account.
  • GET /groupingTypes - Retrieves grouping types for the account movements. Grouping types are relevant when retrieving transactions for invoicing.
  • GET /accounts - Retrieves customer account details by filtering information collected in Vynamic Engage Customer Account Service. User can obtain customer account details and reduce results based on filters.
  • GET /accounts/movementsForStatement - Retrieves customer accounts which require statements generated on a given date.
  • GET /accounts/{id}/movements - Retrieves different types of movement on the local customer account (pay-in, pay-out, refund, etc.).
  • GET /invoiceCadences - Retrieves a list of invoice cadences.

Customer accounts allow customers to delay payment for their purchases, with a credit account being the most commonly used method of payment. This involves the customer signing a contract with the retailer to set up an account with a credit limit (which is usually balanced monthly). They can then use it as a form of payment that can be used instead of cash or card.

Example: Local taxi company, where drivers purchase fuel for their cars at a specific petrol station. Upon the purchase, the drivers provide the account identifier and confirm the purchase by signing the slip or receipt. The retailer issues an invoice for the company (for example on a monthly basis) and the payment is settled as agreed by the retailer and the customer.

The Customers API also exposes the following endpoints related to the customer attributes:

  • GET /attributes/type - Retrieves a collection of types of attributes.
  • GET /attributes - Retrieves a collection of attributes.
  • POST /attributes - Enables the POS system to create attributes.
  • GET /attributes/{id} - Retrieves attributes filtered by its ID.
  • PUT /attributes/{id} - Updates attributes by its ID.
  • DELETE /attributes/{id} - Deletes attributes by their ID.

Health Check: The GET /healthCheck endpoint enables the API client to check the status of the dependent backend services. On the 200 response, the client receives the overall status information: healthy, degraded, unhealthy.

Security

The Customers API supports OAuth 2.0 for authentication purposes.
The supported protocol for the Customers API is HTTPS.