Creating and updating customers

Learn how to create and update a customer.

Once you define a customer, you can create a customer object and then associate the object with checkouts. Once the object is created, you can save one or more payment sources to a customer as well as set a customer's default payment source.

Defining a customer

The following provides guidance on how to define a customer. For complete specifications, refer to the Checkouts API reference documentation.

Unique identifier

A customers id must be forty characters or less in length. Anything longer and a 400 Bad Request with a code of invalid_parameter is returned.

We recommend that a customer's identifier be identical in both your and our systems.

If you don't provide us an id value in the create customer request, we generate one for you and return it in the response.

Email

The email parameter represents a customer's email address. You can create multiple customers in your account that contain identical email values.

Shipping address

You can use shipping to store a customer's name, phone, email, organization, basic ship to address, and detailed ship to additionalAddressInfo.

Tax identifiers and certificates

Every customer can store one or more tax identifiers and tax certificates.

Locale

A customer's locale is used to localize invoices and credit memos.

Customer type

A customer's type allows you to differentiate between business and individual customers.

Enabling a customer

If you set a customer's enabled flag to false, then any attempts to create orders that reference this customer will fail. You should only set enabled to false when you want to block a customer from placing orders. For example, you may decide this is necessary when a customer has a history of fraudulent behavior.

Default payment source

The defaultSourceId should reference a source that customers have indicated is their default payment instrument.

For more information, refer to setting the default payment source on the Managing sources page.

Request to be forgotten

When you update customer requests, you can use requestToBeForgotten to instruct Digital River to delete a customer's data from our system.

For more information, refer to the Recording a customer's request to be forgotten page.

Creating a customer

The process of creating and updating a customer is similar. In a create customer request, you can specify the object's unique identifier. However, when updating a customer, you must pass in this unique identifier as a path parameter.

Updating a customer's request also allows you to record a customer's right to be forgotten.

The following POST/customers request specifies a unique id:

curl --location --request POST 'https://api.digitalriver.com/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
  "id": "5823594806",
  "email": "[email protected]",
  "shipping": {
    "address": {
      "line1": "10380 Bren Rd W",
      "line2": "string",
      "city": "Minnetonka",
      "postalCode": "55129",
      "state": "MN",
      "country": "US"
    },
    "name": "John Smith",
    "phone": "952-111-1111",
    "email": "[email protected]",
    "organization": "Digital River"
  },
  "type": "individual",
  "metadata": {
    "coupon": "iOS"
  },
  "locale": "en_US",
  "enabled": true
}'

A successful request returns a 201 Created whose payload contains a customer object:

{
    "id": "5823594809",
    "createdTime": "2020-05-06T22:28:01Z",
    "email": "[email protected]",
    "shipping": {
        "address": {
            "line1": "10380 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        },
        "phone": "952-111-1111",
        "email": "[email protected]"
    },
    "enabled": true,
    "requestToBeForgotten": false,
    "locale": "en_US",
    "type": "individual",
    "liveMode": false
}

Once you create a customer, you can reference this object in registered checkouts.

Last updated