Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Data API resources 23.2

CustomerLists resource (Data API 23.2)

Summary

Http Method Resource Description
POST /customer_lists/{customer_list_id}/customer_search Action to search for customers in a customer list. The query attribute specifies a complex query that can be used to narrow down the search. Note that a text_query search only returns exact word matches. For example, the search term "Jon" returns "Jon Smith", but doesn't return "Jonathan Smith". These attributes are searchable:
  • customer_no - String
  • first_name - String
  • second_name - String
  • last_name - String
  • suffix - String
  • salutation - String
  • title - String
  • fax - String
  • phone_home - String
  • phone_business - String
  • phone_mobile - String
  • email - String
  • gender - Integer
  • company_name - String
  • credentials.login - String
  • credentials.enabled - boolean
GET /customer_lists/{list_id} Action to read an existing customerlist.
POST /customer_lists/{list_id}/customers Action to create a new customer. The customer is created using the specified credentials and customer information.This action verifies the following:
  • Login acceptance criteria and uniqueness
  • Mandatory customer properties
If the action fails to create the customer, it returns a 400 fault with an appropriate message.
GET /customer_lists/{list_id}/customers/{customer_no} Action to get customer information.
PATCH /customer_lists/{list_id}/customers/{customer_no} Updates the customer with the specified information. The customer number is allowed to be updated but will result in a CustomerNumberAlreadyInUseException if there is already another customer with the same customer number existing.
DELETE /customer_lists/{list_id}/customers/{customer_no} Deletes the customer including all related information like the customer addresses. Returns a status code of 204 on successful completion when deleting the customer. If the customer to be deleted did not exist, a 204 will still be returned to indicate the resource is no longer present in the system.
PUT /customer_lists/{list_id}/customers/{customer_no} Action to create a new customer. The customer is created using the specified customer number, credentials and customer information.This action verifies the following:
  • Login acceptance criteria and uniqueness
  • Mandatory customer properties
If the action fails to create the customer, it returns a 400 fault with an appropriate message.
GET /customer_lists/{list_id}/customers/{customer_no}/addresses Action that returns a pageable list of all customer addresses. The default page size is 10 customer addresses.
POST /customer_lists/{list_id}/customers/{customer_no}/addresses The action creates a new customer address with the given address information.
GET /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id} Action which returns an address of a customer.
PATCH /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id} Action which updates an address of a customer with the given address information.
DELETE /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id} Action which deletes a customer address.

Search for customers in a customer list

Action to search for customers in a customer list. The query attribute specifies a complex query that can be used to narrow down the search. Note that a text_query search only returns exact word matches. For example, the search term "Jon" returns "Jon Smith", but doesn't return "Jonathan Smith". These attributes are searchable:
  • customer_no - String
  • first_name - String
  • second_name - String
  • last_name - String
  • suffix - String
  • salutation - String
  • title - String
  • fax - String
  • phone_home - String
  • phone_business - String
  • phone_mobile - String
  • email - String
  • gender - Integer
  • company_name - String
  • credentials.login - String
  • credentials.enabled - boolean

Url

POST https://hostname:port/dw/data/v23_2/customer_lists/{customer_list_id}/customer_search

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SearchRequest

Response Document

CustomerSearchResult

Path Parameters

Parameter Type Description Constraints
customer_list_id String The customer list id to search in maxLength=256, minLength=1

Sample

REQUEST:
POST /s/-/dw/data/v23_2/customer_lists/SiteGenesis/customer_search HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
     "query" : 
     {
        "text_query": { "fields": ["credentials.login"], "search_phrase":"mmiller" }
     }
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_type" : "customer_search_result",
   "count" : 1,
   "hits" : 
   [
      {
         "_type" : "customer_search_hit",
         "data" : {
            "_type" : "customer",
            "customer_no" : "000007"
         },
         "relevance" : 1.5439257621765137
      }
   ],
   "query" : 
   {
      "text_query" : 
      {
         "_type" : "text_query",
         "fields" : 
         [
            "credentials.login"
         ],
         "search_phrase" : "mmiller"
      }
   },
   "start" : 0,
   "total" : 1
}

Get customer list

Action to read an existing customerlist.

Url

GET https://hostname:port/dw/data/v23_2/customer_lists/{list_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CustomerList

Path Parameters

Parameter Type Description Constraints
list_id String the id of the customerlist minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListNotFoundException

customerListId (String)

 Indicates that there was no customerlist found for the customerlist id.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/customer_lists/SiteGenesis HTTP/1.1
Host: example.com
Authorization:Bearer ac734607-c966-44fb-8739-8ea413a2c0a5
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "customer_list",
   "id" : "SiteGenesis"
}

# in case of failure (SecureCommunicationRequired, i.e. no http):

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "SecureCommunicationRequiredException",
      "message" : "A secure connection is required."
   }
}

# in case of failure (CustomerListNotFound, i.e. invalid customerlist id):

RESPONSE:
HTTP/1.1 404 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "CustomerListNotFoundException",
      "message" : "No customer list with ID 'foobar' was found."
   }
}

Create customer

Action to create a new customer. The customer is created using the specified credentials and customer information.This action verifies the following:
  • Login acceptance criteria and uniqueness
  • Mandatory customer properties
If the action fails to create the customer, it returns a 400 fault with an appropriate message.

Url

POST https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Customer

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidLoginException   Indicates the login does not match the login acceptance criteria.
400 LoginAlreadyInUseException   Indicates the login is already in use.
400 CredentialsMissingException   Indicates that the mandatory credentials are missing in the input document.
400 LoginMissingException   Indicates that the mandatory login property is missing in the input document.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customers.beforePOST

beforePost (create : Customer , customerListId : String ) : Status

The function is called before the customer is created with the given document.

Parameters:
create - the customer create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customers.afterPOST

afterPost (customer : Customer , create : Customer , customerListId : String ) : Status

The function is called after the new customer was created.

Parameters:
customer - the new customer.
create - the customer create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /s/-/dw/data/v23_2/customer_lists/4711/customers HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
  "email":"[email protected]",
  "birthday":"2011-05-06",
  "fax":"",
  "first_name":"",
  "gender":1,
  "job_title":"",
  "last_name":"",
  "phone_business":"",
  "phone_home":"",
  "phone_mobile":"",
  "preferred_locale":"en-US",
  "salutation":"",
  "second_name":"",
  "suffix":"",
  "title":"",
  "company_name":"",
  "credentials":
  {
    "password_question" : "Mother's maiden name",
    "login":"foo"
  }
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT

{
  "_v" : "23.2",
  "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5"
  "_type":"customer",
  "customer_no":"0815"
  "email":"[email protected]",
  "birthday":"2011-05-06",
  "fax":"",
  "first_name":"",
  "gender":1,
  "job_title":"",
  "last_name":"",
  "phone_business":"",
  "phone_home":"",
  "phone_mobile":"",
  "preferred_locale":"en-US",
  "salutation":"",
  "second_name":"",
  "suffix":"",
  "title":"",
  "company_name":"",
  "credentials":
  {
    "password_question" : "Mother's maiden name",
    "login":"foo"
  }
}
 
# in case of validation failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"InvalidPasswordException",
    "message":"The password does not meet the requirements."
  }
}

Get customer

Action to get customer information.

Url

GET https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/customer_lists/4711/customers/0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type":"customer",
  "birthday" : "1970-01-31",
  "company_name" : "Salesforce Commerce Cloud",
  "creation_date" : "2013-09-17T09:20:31.000Z",
  "credentials" : {
    "enabled" : true,
    "locked" : false,
    "password_question" : "Mother's maiden name",
    "login" : "dude"
  },
  "customer_no" : "0815",
  "email" : "[email protected]",
  "fax" : "001-444-4444",
  "first_name" : "",
  "job_title" : "",
  "last_name" : "",
  "phone_business" : "001-222-2222",
  "phone_home" : "001-111-1111",
  "phone_mobile" : "001-333-3333",
  "preferred_locale" : "de_DE",
  "salutation" : "Mr.",
  "second_name" : "second",
  "suffix" : "suffix",
  "title" : "Dr."
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"CustomerListCustomerNotFoundException",
    "message":"No customer with number '0815' for customer list '4711' was found."
  }
}

Update customer

Updates the customer with the specified information. The customer number is allowed to be updated but will result in a CustomerNumberAlreadyInUseException if there is already another customer with the same customer number existing.

Url

PATCH https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Customer

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidLoginException   Indicates the login does not match the login acceptance criteria.
400 LoginAlreadyInUseException   Indicates the login is already in use.
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customer.beforePATCH

beforePatch (customer : Customer , update : Customer , customerListId : String ) : Status

The function is called before the customer is updated with update document.

Parameters:
customer - the customer to update.
update - the update document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customer.afterPATCH

afterPatch (customer : Customer , update : Customer , customerListId : String ) : Status

The function is called after the customer is updated with update document.

Parameters:
customer - the customer to update.
update - the update document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/customer_lists/4711/customers/0815 HTTP/1.1
Host: example.com
{
  "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_delete":["fax","phone_mobile"],         // delete values of properties "fax" and "phone_mobile"
  "birthday":"2011-05-06",                  // update "birthday"
  "email":"[email protected]"             // update "email"
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73b8h6",
  "_type":"customer",
  "birthday":"2011-05-06",
  "customer_number":"0815",
  "email":"[email protected]",
  "fax":"",
  "first_name":"Dude",
  "gender":"m",
  "job_title":"",
  "last_name":"Lebowski",
  "phone_business":"",
  "phone_home":"",
  "phone_mobile":"",
  "preferred_locale":"en-US",
  "salutation":"",
  "second_name":"",
  "suffix":"",
  "title":""
}
 
# in case of validation failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 47
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"InvalidEmailException",
    "message":"The customer email address '[email protected]' is not valid."
  }
}

Delete customer

Deletes the customer including all related information like the customer addresses.

Returns a status code of 204 on successful completion when deleting the customer. If the customer to be deleted did not exist, a 204 will still be returned to indicate the resource is no longer present in the system.

Url

DELETE https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customer.beforeDELETE

beforeDelete (customer : Customer , customerListId : String ) : Status

The function is called before the customer is deleted.

Parameters:
customer - the customer to be deleted.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customer.afterDELETE

afterDelete (customerListId : String ) : Status

The function is called after the customer was deleted.

Parameters:
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/customer_lists/4711/customers/0815 HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:
 
RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_type":"fault",
  "fault":{
    "type":"CustomerListCustomerNotFoundException",
    "message":"No customer with number '0815' for customer list '4711' was found."
  }
}

Create customer with given customer number

Action to create a new customer. The customer is created using the specified customer number, credentials and customer information.This action verifies the following:
  • Login acceptance criteria and uniqueness
  • Mandatory customer properties
If the action fails to create the customer, it returns a 400 fault with an appropriate message.

Url

PUT https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Customer

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidLoginException   Indicates the login does not match the login acceptance criteria.
400 CredentialsMissingException   Indicates that the mandatory credentials are missing in the input document.
400 LoginMissingException   Indicates that the mandatory login property is missing in the input document.
400 LoginAlreadyInUseException   Indicates that the given login is already in use.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customers.beforePUT

beforePut (create : Customer , customerListId : String ) : Status

The function is called before the customer is created with the given document.

Parameters:
create - the customer create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customers.afterPUT

afterPut (customer : Customer , create : Customer , customerListId : String ) : Status

The function is called after the new customer was created.

Parameters:
customer - the new customer.
create - the customer create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /s/-/dw/data/v23_2/customer_lists/4711/customers/0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
  "email":"[email protected]",
  "birthday":"2011-05-06",
  "fax":"",
  "first_name":"",
  "gender":1,
  "job_title":"",
  "last_name":"",
  "phone_business":"",
  "phone_home":"",
  "phone_mobile":"",
  "preferred_locale":"en-US",
  "salutation":"",
  "second_name":"",
  "suffix":"",
  "title":"",
  "company_name":"",
  "credentials":
  {
    "password_question" : "Mother's maiden name",
    "login":"foo"
  }
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "23.2",
  "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type":"customer",
  "customer_no":"0815"
  "email":"[email protected]",
  "birthday":"2011-05-06",
  "fax":"",
  "first_name":"",
  "gender":1,
  "job_title":"",
  "last_name":"",
  "phone_business":"",
  "phone_home":"",
  "phone_mobile":"",
  "preferred_locale":"en-US",
  "salutation":"",
  "second_name":"",
  "suffix":"",
  "title":"",
  "company_name":"",
  "credentials":
  {
    "password_question" : "Mother's maiden name",
    "login":"foo"
  }
}
 
# in case of validation failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"InvalidPasswordException",
    "message":"The password does not meet the requirements."
  }
}

Get all customer addresses

Action that returns a pageable list of all customer addresses. The default page size is 10 customer addresses.

Url

GET https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}/addresses?start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CustomerAddressResult

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer The maximum number of instances per request. Default value is 25. maxIntegerValue=200, minIntegerValue=1
start Integer The result set index to return the first instance for. Default value is 0. minIntegerValue=0

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/customer_lists/4711/customers/0815/addresses HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
  
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_type":"customer_address_result",
  "count" : 10,
  "data" : [ {
    "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
    "address1" : "Lodyweg",
    "address_id" : "my_home_address",
    "city" : "Washingtonville",
    "company_name" : "Salesforce Commerce Cloud",
    "country_code" : "SH",
    "first_name" : "Pit",
    "full_name" : "Pit Snipes",
    "job_title" : "",
    "last_name" : "Snipes",
    "phone" : "001-111-1111",
    "postal_code" : "15361",
    "state_code" : "DE"
  }, 
  ...
  } ],
  "next" : "https://example.com/dw/data/v23_2/customer_lists/4711/customers/0815/addresses?count=10&start=10",
  "start" : 0,
  "total" : 151
}

Create customer address

The action creates a new customer address with the given address information.

Url

POST https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}/addresses

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomerAddress

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidAddressIdException   If the address id is null or empty.
400 AddressIdAlreadyInUseException   If the address id is already in use.
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customer.addresses.beforePOST

beforePost (customer : Customer , create : CustomerAddress , customerListId : String ) : Status

The function is called before a customer address is created with the given document.

Parameters:
customer - the customer the address should be created for.
create - the customer address create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customer.addresses.afterPOST

afterPost (customer : Customer , customerAddress : CustomerAddress , create : CustomerAddress , customerListId : String ) : Status

The function is called after the new customer address was created.

Parameters:
customer - the customer the address should be created for.
customerAddress - the new customer address.
create - the customer address create document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /s/-/dw/data/v23_2/customer_lists/4711/customers/0815/addresses HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

{
  "address_id":"my_home_address"
  "salutation":"",
  "title":"",
  "company_name":"",
  "first_name":"",
  "second_name":"",
  "last_name":"",
  "postal_code":"",
  "address1":"",
  "address2":"",
  "city":"",
  "post_box":"",
  "country_code":"",
  "state_code":"",
  "phone":"",
  "suffix":""
}

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type":"customer_address",
  "address_id":"my_home_address"
  "salutation":"",
  "title":"",
  "company_name":"",
  "first_name":"",
  "second_name":"",
  "last_name":"",
  "postal_code":"",
  "address1":"",
  "address2":"",
  "city":"",
  "post_box":"",
  "country_code":"",
  "state_code":"",
  "phone":"",
  "suffix":""
}

# in case of validation failure:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"AddressIdAlreadyInUseException",
    "message":"The customer address ID is already in use."
  }
}

Get customer address

Action which returns an address of a customer.

Url

GET https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
address_id String The address id minLength=1
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.
404 CustomerListCustomerAddressNotFoundException

addressId (String)

customerNo (String)

customerListId (String)

 Indicates that the customer address id is unknown.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/customer_lists/4711/customers/dude/addresses/myaddress HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
  
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type":"customer_address",
  "address1":"10 Somewhere St.",
  "address2":"",  
  "address_id":"myaddress"
  "city":"Boston",
  "company_name":"",
  "country_code":"",
  "first_name":"Egon",
  "full_name":"Egon Krenz",
  "job_title":"",
  "last_name":"Krenz",
  "phone":"",
  "postal_code":"",
  "post_box":"",
  "salutation":"",
  "second_name":"",
  "state_code":"",
  "suffix":"",
  "suite":"",
  "title":""
}

Update customer address

Action which updates an address of a customer with the given address information.

Url

PATCH https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomerAddress

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
address_id String The address id minLength=1
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidAddressIdException   If the new address id is empty.
400 AddressIdAlreadyInUseException   If the new address id is already in use.
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.
404 CustomerListCustomerAddressNotFoundException

addressId (String)

customerNo (String)

customerListId (String)

 Indicates that the customer address id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customer.address.beforePATCH

beforePatch (customer : Customer , customerAddress : CustomerAddress , update : CustomerAddress , customerListId : String ) : Status

The function is called before the customer address is updated with update document.

Parameters:
customer - the customer the address should be updated for.
customerAddress - the customer address to update.
update - the update document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customer.address.afterPATCH

afterPatch (customer : Customer , customerAddress : CustomerAddress , update : CustomerAddress , customerListId : String ) : Status

The function is called after the customer address is updated with update document.

Parameters:
customer - the customer the address should be updated for.
update - the update document.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/customer_lists/4711/customers/0815/addresses/my_home_address HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
  "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73b8h6",
  "_delete":["first_name","phone"],         // delete values of properties "first_name" and "phone"
  "city":"Burlington",                      // update "city"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type":"customer_address",
  "address1":"10 Somewhere St.",
  "address2":"",  
  "address_id":"my_home_address"
  "city":"Burlington",
  "company_name":"",
  "country_code":"",
  "full_name":"Egon Krenz",
  "job_title":"",
  "last_name":"Krenz",
  "postal_code":"",
  "post_box":"",
  "salutation":"",             
  "second_name":"",
  "state_code":"",
  "suffix":"",
  "suite":"",
  "title":""
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 47
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
   "type":"CustomerListCustomerAddressNotFoundException",
    "message":"No customer address 'my_home_address' for customer with number '0815' in customer list '4711' was found."
  }
}

Delete customer address

Action which deletes a customer address.

Url

DELETE https://hostname:port/dw/data/v23_2/customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
address_id String The address id minLength=1
customer_no String The customer number minLength=1
list_id String The customer list id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerListCustomerNotFoundException

customerNo (String)

customerListId (String)

 Indicates that the customer with the given customer number is unknown.
404 CustomerListNotFoundException

customerListId (String)

 Indicates that the customer list with the given customer list id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.customer_list.customer.address.beforeDELETE

beforeDelete (customer : Customer , customerAddress : CustomerAddress , customerListId : String ) : Status

The function is called before the customer is deleted.

Parameters:
customer - the customer the address should be deleted for.
customerAddress - the customer address to be deleted.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.customer_list.customer.address.afterDELETE

afterDelete (customer : Customer , customerListId : String ) : Status

The function is called after the customer address was deleted.

Parameters:
customer - the customer the address should be deleted for.
customerListId - the id of the customerlist the customer is assigned to
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/customer_lists/4711/customers/0815/addresses/my_home_address HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:
 
RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "_type":"fault",
  "fault":{
    "type":"CustomerListCustomerAddressNotFoundException",
    "message":"No customer address 'my_home_address' for customer with number '0815' in customer list '4711' was found."
  }
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.