Quick Menu

Customer management

An overview of the typical use case handling for creating new customers and update customer data.

The creation/registration of a new customer is the first step in the subscription process. It is the prerequisite for creating and sending orders. This page serves to demonstrate how to manage the basic data for a customer in the subscriptions module including create, update and read functionality.

Please note that the following use cases require the customer information to exist:

How it works

When creating a new customer, the following process steps will take place:

  1. Customer places an order and/or creates an account in the webshop.
  2. Merchant passes the customer data to Accounting as a Service.
  3. Internally, Accounting as a Service checks if the customer is already existing by trying to get existing customer information. In case the customer already exists, the customer information will be updated. Otherwise, the customer will be created.
  4. (Optional) To change customer information (e.g. in case a customer wants to change the billing address), the merchant updates the existing customer information whenever needed. The endpoint can also be used to update the payment method (e.g. the customer wants to change the payment method were monthly subscriptions are deducted from).
High-level process description
A process overview using BPMN
Checkout the BPMN illustration to get an overview of the process, including the various activities and participating main actors.
Open in new tab

How to implement

Get customer information

To retrieve information about an existing customer, make a GET /subscriptions/{version}/customers/{customerNumber} request, where {customerNumber} is the identifier of the related customer that you would like to get the details for.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
GET /subscriptions/v1/customers/c1631704458 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "customerNumber": "c1631704458",
  "salutation": "MR",
  "firstName": "Ray",
  "lastName": "Ankunding",
  "address": {
    "street": "Bergnaum Mountains",
    "postalCode": "97687-7791",
    "postalPlace": "Schadenville",
    "countryCode": "DE",
    "streetNumber": "1"
  },
  "taxIdentificationNumber": "12345678L",
  "identificationNumber": "700XXX651",
  "email": "Ray_Ankunding43@gmail.com",
  "companyName": "",
  "birthDate": "1984-11-11",
  "language": "DE",
  "customerCategory": "PERSON",
  "phone": "871.790.7578 x4882",
  "mobilePhone": "+37258774XXX"
}

Create a new customer

If you want to create a new customer, make a POST /subscriptions/{version}/customers request. Beside the general customer information such as the first name, last name or address, you will also have to provide the related payment registration the customer shall be linked to.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
POST /subscriptions/v1/customers HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
  "customer": {
    "address": {
      "careOf": "",
      "countryCode": "DE",
      "postalCode": "97687-7791",
      "postalPlace": "Schadenville",
      "street": "Bergnaum Mountains",
      "streetNumber": "1",
      "streetNumberAdditional": "a"
    },
    "birthDate": "1984-11-11",
    "companyName": "",
    "customerCategory": "PERSON",
    "customerNumber": "c1631704458",
    "email": "Ray_Ankunding43@gmail.com",
    "firstName": "Ray",
    "identificationNumber": "700XXX651",
    "language": "de",
    "lastName": "Ankunding",
    "mobilePhone": "+37258774XXX",
    "phone": "871.790.7578 x4882",
    "salutation": "MR",
    "taxIdentificationNumber": "12345678L"
  },
  "paymentRegistration": {
    "id": "275122"
  }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "signUpId": 702091815,
  "customerNumber": "700427690",
  "externalCustomerReference": "c1631704458",
  "contracts": []
}

Update customer information

In order to update the information of an existing customer, make a PUT /subscriptions/{version}/customers/{customerNumber} request, where {customerNumber} is the identifier of the related customer that you would like to update. The information to be provided is identical to the information needed when creating a new customer.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
PUT /subscriptions/v1/customers/c1631704458 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
  "customer": {
    "address": {
      "careOf": "",
      "countryCode": "DE",
      "postalCode": "97687-7791",
      "postalPlace": "Schadenville",
      "street": "Bergnaum Mountains",
      "streetNumber": "1",
      "streetNumberAdditional": "a"
    },
    "birthDate": "1984-11-11",
    "companyName": "",
    "customerCategory": "PERSON",
    "customerNumber": "c1631704458",
    "email": "Ray_Ankunding43@gmail.com",
    "firstName": "Ray",
    "identificationNumber": "700XXX651",
    "language": "de",
    "lastName": "Ankunding",
    "mobilePhone": "+37258774XXX",
    "phone": "871.790.7578 x4882",
    "salutation": "MR",
    "taxIdentificationNumber": "12345678L"
  },
  "paymentRegistration": {
    "id": "275122"
  }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "signUpId": 702091815,
  "customerNumber": "700427690",
  "externalCustomerReference": "c1631704458",
  "contracts": []
}

See also