Customers Resource (Shop API 16.2)

Summary

Http Method Resource Description
POST /Customers

Registers a customer. The mandatory data are the credentials and profile last name and email.

When using OAuth the password in the request must not be set, otherwise an InvalidPasswordException will be thrown.

When using JWT the password is required.
POST /Customers/Auth Obtains a new JWT (JSON Web Token) for a guest or registered customer. Tokens are returned as a HTTP Authorization:Bearer response header entry. These kinds of request are supported, as specified by the type:
  • Type guest - creates a new guest (non-authenticated) customer and returns a token for the customer.
  • Type credentials - authenticates credentials passed in the HTTP Authorization:Basic request header, returning a token for a successfully authenticated customer otherwise results in an AuthenticationFailedException.
  • Type session - authenticates the customer (anonymous or registered) on base of dwsid and dwsecuretoken cookies. It returns a token for a successfully authenticated customer, otherwise results in an AuthenticationFailedException.
  • Type refresh - examines the token passed in the HTTP Authorization:Bearer request header and when valid returns a new token with an updated expiry time.
For a request of type credentials:
  • Updates profile attributes for the customer (for example, "last-visited").
  • Handles the maximum number of failed login attempts.
For a request of type session:
  • Does not touch profile attributes for the registered customer (for example, "last-visited"), since this is not a real login.
  • Returns different tokens for multiple requests with the same session id. Means, there should be only one call per session.

About JWT

The token contains 3 sections:
  • the header section (specifies token type and algorithm used)
  • the payload section (contains customer information, client id, issue and expiration time)
  • finally the signature section records the token signature.
A token is created and returned to the client whenever a registered customer logs in (type "credentials") or a guest customer requests it (type "guest"). The token is returned in the response header as

Authorization: Bearer --token--

The client has to include the token in the request header as

Authorization: Bearer --token--

in any follow up request. The server declines any follow up requests without a token or which cannot be verified based on the token signature or expiration time. A token nearing its expiration time should be exchanged for a new one (type "refresh").

See "API Usage > JWT" for more details on using JWT as an authentication mechanism.
POST /Customers/Password_reset Starts a password reset process. A password reset token is generated and together with the resolved customer is passed to a afterPOST hook. The customer resolution is based on the password reset request type. Currently the resolution can be done by email or login. In case of an email the password reset hook is only executed if one and only one customer has been identified for that email. In the case that more than one customers have been identified for the provided email the resource does nothing.
GET /Customers/{Customer_id} Gets a customer.
PATCH /Customers/{Customer_id} Updates a customer.
GET /Customers/{Customer_id}/Addresses Returns a sorted pageable list of all customer addresses in the address book. The default page size is 10 customer addresses. The addresses are sorted so that the preferred address is always sorted first. The remaining addresses are sorted alphabetically by ID.
POST /Customers/{Customer_id}/Addresses Creates a new address with the given name for the given customer.
GET /Customers/{Customer_id}/Addresses/{Address_name} Retrieves a customer's address by address name.
DELETE /Customers/{Customer_id}/Addresses/{Address_name} Deletes a customer's address by address name.
PATCH /Customers/{Customer_id}/Addresses/{Address_name} Updates a customer's address by address name.
GET /Customers/{Customer_id}/Baskets Gets the baskets of a customer.
GET /Customers/{Customer_id}/Orders Returns a pageable list of all customer's orders. The default page size is 10.
PUT /Customers/{Customer_id}/Password Updates the customer's password.
POST /Customers/{Customer_id}/Password_reset Starts a password reset process. A password reset token is generated and passed together with the customer resolved by the id provided as path parameter to a afterPOST hook. The hook dw.ocapi.shop.customer.password_reset.afterPOST can utilize the provided reset token, for example to send a reset email.
GET /Customers/{Customer_id}/Payment_instruments Gets customer payment instruments for an customer.

Can be limited to a specific payment method by providing query parameter payment_method_id.
POST /Customers/{Customer_id}/Payment_instruments Adds a payment instrument to a customer information.
GET /Customers/{Customer_id}/Payment_instruments/{Payment_instrument_id} Retrieves a customer's payment instrument by its id.
DELETE /Customers/{Customer_id}/Payment_instruments/{Payment_instrument_id} Deletes a customer's payment instrument.

Register Customer

Registers a customer. The mandatory data are the credentials and profile last name and email.

When using OAuth the password in the request must not be set, otherwise an InvalidPasswordException will be thrown.

When using JWT the password is required.

Url

POST https://hostname:port/dw/shop/v16_2/customers

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

CustomerRegistration

Response Document

Customer

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CustomerAlreadyRegisteredException   Indicates that the resource is called with JWT token representing a registered customer.
400 MissingEmailException   Indicates that request document does not contain email.
400 MissingLastNameException   Indicates that request document does not contain last_name.
400 MissingLoginException   Indicates that request document does not contain login.
400 LoginAlreadyInUseException   Indicates that the given login is already used.
400 InvalidLoginException   Indicates that login doesn't match acceptance criteria.
400 InvalidPasswordException   Indicates that password doesn't match acceptance criteria.
400 MissingPasswordException   Indicates that password was not provided in JWT scenario.
400 InvalidEmailException

email (String)

 Indicates that the profile email address is not valid.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterPost

afterPost (customer : Customer , registration : CustomerRegistration ) : Status

The function is called after a new customer registration.

Parameters:
customer - the registered customer
registration - the customer registration information
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforePost

beforePost (registration : CustomerRegistration ) : Status

The function is called before a new customer registration.

Parameters:
registration - the customer registration information
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v16_2/customers
Host: example.com
Content-Type: application/json

{ 
  "password":"12345!aBcD",
  "customer": {
                "login": "jsmith"
                "email":"[email protected]",
                "last_name":"Smith"
               }
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer",
   "auth_type" : "registered",
   "creation_date" : "2015-09-09T15:50:53.142Z",
   "customer_id" : "ada5ZiobJRE4Ma1fSaAogMDKgI",
   "customer_no" : "00001140",
   "email" : "[email protected]",
   "last_name" : "Smith",
   "login" : "jsmith"
}


# 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: no-cache,no-store,must-revalidate

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "LoginAlreadyInUseException",
      "message" : "Login is already in use."
   }
}

Get or Refresh Customer JWT (JSON Web Token)

Obtains a new JWT (JSON Web Token) for a guest or registered customer. Tokens are returned as a HTTP Authorization:Bearer response header entry. These kinds of request are supported, as specified by the type:

For a request of type credentials: For a request of type session:

About JWT

The token contains 3 sections: A token is created and returned to the client whenever a registered customer logs in (type "credentials") or a guest customer requests it (type "guest"). The token is returned in the response header as

Authorization: Bearer --token--

The client has to include the token in the request header as

Authorization: Bearer --token--

in any follow up request. The server declines any follow up requests without a token or which cannot be verified based on the token signature or expiration time. A token nearing its expiration time should be exchanged for a new one (type "refresh").

See "API Usage > JWT" for more details on using JWT as an authentication mechanism.

Url

POST https://hostname:port/dw/shop/v16_2/customers/auth

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

AuthRequest

Response Document

Customer

Header Parameters

Parameter Type Description Constraints
Authorization String
  • Authorization:Basic for type credentials
  • Authorization:Bearer for type refresh
 

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 AuthorizationBasicMissingException   Indicates that no HTTP Authorization:Basic header was provided.
401 AuthenticationFailedException

credentialType (String)

 Indicates in case of type credentials the username is unknown or the password does not match. In case of type session the session is not active anymore or the dwsecuretoken value is invalid. In both cases the customer is disabled or locked.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.auth.afterAuth

afterAuth (authRequestType : EnumValue , customer : Customer ) : Status

The function is called after the customer has been authenticated.

Parameters:
customer - the customer that is authenticated, might be a guest or registered customer
authRequestType - does the request specify a guest, login or refresh authentication
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

# Request type guest : obtain a token for a guest customer

REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Content-Type: application/json

{
  "type" : "guest"
}

# Request type credentials : obtain a token for a registered customer
# Credentials are passed as HTTP Basic in base 64 in the form username:password

REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
  "type" : "credentials"
}

# Request type session : obtain a token for a session
# session information passed as cookies

REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==;

{
  "type" : "session"
}

# Request type refresh : obtain a token in exchange for a token nearing expiration time
# Same mechanism used for guest and registered customer. Client ID needs to
# be provided and is checked against the id embedded in the token being refreshed.

REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Host: example.com
Content-Type: application/json

{
  "type" : "refresh"
}


# in case of success, token returned in response header Authorization:Bearer
# "auth_type" is one of "guest" or "registered"

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer",
   "auth_type" : "guest",
   "customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
   "preferred_locale" : "default"
}

# in case attempt to refresh an expired token:

RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "ExpiredTokenException",
      "message" : "The provided token has expired."
   }
}

# in case no Authorization Basic provided for type "credentials"

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "AuthorizationBasicMissingException",
      "message" : "Missing credentials: Add a Authorization:Basic header with base64 encoded username:password."
   }
}

# in case missing or wrong username/password for type "credentials"

RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "AuthenticationFailedException",
      "message" : "Failed to authenticate customer on base of Authorization:Basic header."
   }
}

# in case of an outdated session for type "session"

RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "AuthenticationFailedException",
      "message" : "Failed to authenticate customer on base of session."
   }
}

Starts a Password Reset Process

Starts a password reset process. A password reset token is generated and together with the resolved customer is passed to a afterPOST hook. The customer resolution is based on the password reset request type. Currently the resolution can be done by email or login. In case of an email the password reset hook is only executed if one and only one customer has been identified for that email. In the case that more than one customers have been identified for the provided email the resource does nothing.

Url

POST https://hostname:port/dw/shop/v16_2/customers/password_reset

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

PasswordReset

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customers.password_reset.afterPOST

afterPOST (customer : Customer , resetToken : String ) : Status

Allows resetting a customer password. See the example below sending an email with a password reset link. 
 var variables: Map = new dw.util.HashMap();
 variables.put("Customer", customer);
 variables.put("ResetPasswordToken", token);
 var template: Template = new dw.util.Template("mail/resetpasswordemail.isml");
 var content: MimeEncodedText = template.render(variables);
 var mail: Mail = new Mail().setSubject("Password Reset").setContent(content).setFrom("[email protected]").addTo(customer.profile.email);
 mail.send();
Parameters:
customer - the customer for whom to reset the password
resetToken - the token generated by the system to be used for the reset
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Password reset
#
REQUEST:
POST /dw/shop/v16_2/customers/password_reset
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8

{"identification": "[email protected]", "type":"email"}

# in case of success:

RESPONSE:
HTTP/1.1 204 NO CONTENT

# in case of password reset failure in hook dw.ocapi.shop.customers.password_reset.afterPOST.
# The wrong status with code and message is returned by the custom code.

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "arguments" : 
      {
         "extensionPoint" : "dw.ocapi.shop.customers.password_reset.afterPOST",
         "statusCode" : "EXT_PW_CHANGE_FAIL",
         "statusMessage" : "Password reset not successful in external system."
      },
      "type" : "HookStatusException",
      "message" : "Error in ExtensionPoint 'dw.ocapi.shop.customers.password_reset.afterPOST'!"
   }
}

Get Customer

Gets a customer.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_id String The customer id mandatory=true, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The expand parameter. A comma separated list with the allowed values (addresses, paymentinstruments).  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   If customerId URL parameter does not match the verified customer represented by the JWT token (not relevant when using OAuth).
404 CustomerNotFoundException

customerId (String)

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

Sample

REQUEST:
GET /dw/shop/v16_2/customers/1234567890?expand=addresses,paymentinstruments HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
ETag: y4ad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd438kl
Cache-Control: max-age=0,no-cache,no-store,must-revalidate

{
   "_v" : "16.2",
   "_type" : "customer",
   "adresses" : 
   [
      {
         "_type" : "customer_address",
         "address1" : "10 Presidential Way",
         "address_id" : "me",
         "city" : "Woburn",
         "country_code" : "US",
         "first_name" : "John",
         "full_name" : "John M. Smith",
         "last_name" : "Smith",
         "postal_code" : "01801",
         "salutation" : "Mr.",
         "state_code" : "MA"
      }
   ],
   "auth_type" : "registered",
   "creation_date" : "2015-08-20T11:30:36.000Z",
   "customer_id" : "abfTWMDZOgi3JPzkHjv9IhmziI",
   "customer_no" : "999",
   "email" : "[email protected]",
   "first_name" : "John",
   "gender" : 1,
   "last_name" : "Smith",
   "payment_instruments" : 
   [
      {
         "_type" : "customer_payment_instrument",
         "payment_bank_account" : 
         {
            "_type" : "payment_bank_account"
         },
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "John Smith",
            "masked_number" : "***********ber2",
            "number_last_digits" : "ber2"
         },
         "payment_instrument_id" : "beybQiWcyatEEaaadniwhKxxFl",
         "payment_method_id" : "CREDIT_CARD",
         "uuid" : "beybQiWcyatEEaaadniwhKxxFl",
      }
   ],
   "phone_business" : "234560003",
   "phone_home" : "123450003",
   "phone_mobile" : "345670003",
   "c_origin" : "webshop"
}

# in case the authorized customer differs from the customer requested:
 
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":"16.2",
  "_type":"fault",
  "fault":{
    "type":"InvalidCustomerException",
    "message":"Invalid customer."
  }
}

Updates a Customer

Updates a customer.

Url

PATCH https://hostname:port/dw/shop/v16_2/customers/{customer_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

Customer

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_id String the customer id minLength=1

Header Parameters

Parameter Type Description Constraints
If-Match String    

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
400 InvalidEmailException

email (String)

 Indicates that the provided email is not valid.
404 CustomerNotFoundException

customerId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterPatchCustomer

afterPatchCustomer (customer : Customer , customerInput : Customer ) : Status

The function is called after a customer was updated.

Parameters:
customer - the customer to be updated
customerInput - the input customer containing the patch changes
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforePatchCustomer

beforePatchCustomer (customer : Customer , customerInput : Customer ) : Status

The function is called before a customer is updated.

Parameters:
customer - the customer to be updated
customerInput - the input customer containing the patch changes
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v16_2/customers/1234567890 HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
Content-Type: application/json
{
   email : "[email protected]",
   fax : "+49 03641 78393 343",
   c_origin :"webshop"
}
# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
Content-Type:application/json;charset=UTF-8

{
   "auth_type" : "registered",
   "creation_date" : "2015-08-20T11:30:36.000Z",
   "customer_id" : "abfTWMDZOgi3JPzkHjv9IhmziI",
   "customer_no" : "999",
   "email" : "[email protected]",
   "fax" : "+49 03641 78393 343",
   "first_name" : "John",
   "gender" : 1,
   "last_name" : "Smith",
   "phone_business" : "234560003",
   "phone_home" : "123450003",
   "phone_mobile" : "345670003",
   "c_origin" : "webshop"
}

Get All Customer Addresses

Returns a sorted pageable list of all customer addresses in the address book. The default page size is 10 customer addresses. The addresses are sorted so that the preferred address is always sorted first. The remaining addresses are sorted alphabetically by ID.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses?start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

CustomerAddressResult

Path Parameters

Parameter Type Description Constraints
customer_id String The customer uuid 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. maxIntegerValue=999, minIntegerValue=0

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Sample

# Request, no paging details

REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json;charset=UTF-8

# Request, with paging details

REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?start=0&count=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json;charset=UTF-8


# in case of success
# note: "next" and / or "previous" links only exist when appropriate, and only if paging details were provided

RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer_address_result",
   "count" : 1,
   "data" : 
   [
      
      {
         "_type" : "customer_address",
         "address1" : "10 Free Way",
         "address_id" : "private",
         "city" : "Woburn",
         "country_code" : "US",
         "etag" : "0d715f5b688ff38c1f3394d56b84ddc40ca787b1adc6d62953713923b94f9cda",
         "first_name" : "James",
         "full_name" : "James Last",
         "last_name" : "Last",
         "postal_code" : "01801",
         "salutation" : "Mr.",
         "state_code" : "MA"
      }
   ],
   "next" : "https://.../s/.../dw/shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?count=1&start=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "start" : 0,
   "total" : 2
}

Create Customer Address

Creates a new address with the given name for the given customer.

Url

POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

CustomerAddress

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer to create the address for minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
400 InvalidCustomerAddressIdException

addressId (String)

 Indicates that address name is not provided or it's blank.
400 AddressIdAlreadyInUseException   Indicates that the provided address name is already used for the customer.
404 CustomerNotFoundException

customerId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterPostAddress

afterPostAddress (customer : Customer , addressName : String ) : Status

The function is called after adding an address to a customer.

Parameters:
customer - the customer for whom the address was added
addressName - the name of the address which was added
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforePostAddress

beforePostAddress (customer : Customer , addressName : String ) : Status

The function is called before adding an address to a customer.

Parameters:
customer - the customer for whom to add the address
addressName - the name of the address to be added
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

{
  "address_id": "home_address",
  "address1" : "5 Wall St",
  "address2" : "24 Presidential Way",
  "city" : "Burlington",
  "company_name" : "Salesforce",
  "country_code" : "US",
  "first_name": "John",
  "job_title" : "Developer",
  "last_name" : "Murphy",
  "phone" : "408-555-1212",
  "postal_code" : "01805",
  "post_box" : "12a",
  "preferred" : false,
  "salutation" : "Mr.",
  "second_name" : "Jim",
  "state_code": "MA",
  "title": "Dr."
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220

{
   "_v" : "16.2",
   "_type" : "customer_address",
   "address1" : "5 Wall St",
   "address2" : "24 Presidential Way",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce",
   "country_code" : "US",
   "first_name" : "John",
   "full_name" : "John Jim Murphy",
   "job_title" : "Developer",
   "last_name" : "Murphy",
   "phone" : "408-555-1212",
   "postal_code" : "01805",
   "post_box" : "12a",
   "preferred" : false,
   "salutation" : "Mr.",
   "second_name" : "Jim",
   "state_code" : "MA",
   "title" : "Dr."
}


# in case of validation failure - example response in case address_id is already used for this customer:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "AddressNameAlreadyInUseException",
      "message" : "Customer address id is already in use."
   }
}

Get Customer Address

Retrieves a customer's address by address name.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
address_name String the name of the address to retrieve maxLength=256, minLength=1
customer_id String the id of the customer to retrieve the address for minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown.
404 CustomerAddressNotFoundException

addressId (String)

customerNo (String)

siteId (String)

 Indicates that the address with the given name in unknown for the customer with the given customer id.

Sample

REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer_address",
   "address1" : "5 Wall St",
   "address2" : "24 Presidential Way",
   "address_id" : "59aed97608cf7f72",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce",
   "country_code" : "US",
   "first_name" : "John",
   "full_name" : "John J. Murphy",
   "job_title" : "Developer",
   "last_name" : "Murphy",
   "phone" : "408-555-1212",
   "postal_code" : "01805",
   "post_box" : "12a",
   "preferred" : false,
   "salutation" : "Mr.",
   "second_name" : "J.",
   "state_code" : "MA",
   "title" : "Dr."
}

# in case of validation failure - example response in case of unknown address:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "Customer address 'home_address' not found."
   }
}

Delete Customer Address

Deletes a customer's address by address name.

Url

DELETE https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
address_name String the name of the address to delete maxLength=256, minLength=1
customer_id String the id of the customer to delete the address for minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown.
404 CustomerAddressNotFoundException

addressId (String)

customerNo (String)

siteId (String)

 Indicates that the address with the given name in unknown for the customer with the given customer id.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterDeleteAddress

afterDeleteAddress (customer : Customer , addressName : String ) : Status

The function is called after removing an address of a customer.

Parameters:
customer - the customer for whom the address was deleted
addressName - the name of the address which was deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforeDeleteAddress

beforeDeleteAddress (customer : Customer , addressName : String ) : Status

The function is called before removing an address of a customer.

Parameters:
customer - the customer for whom to delete the address
addressName - the name of the address to be deleted
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 204 NO CONTENT


# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Update Customer Address

Updates a customer's address by address name.

Url

PATCH https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

CustomerAddress

Response Document

CustomerAddress

Path Parameters

Parameter Type Description Constraints
address_name String the name of the address to update maxLength=256, minLength=1
customer_id String the id of the customer to update the address for minLength=1

Header Parameters

Parameter Type Description Constraints
If-Match String the ETag header value contained in the server response  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
400 AddressIdAlreadyInUseException   Indicates that the provided new address name is already used for the customer.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown.
404 CustomerAddressNotFoundException

addressId (String)

customerNo (String)

siteId (String)

 Indicates that the address with the given name in unknown for the customer with the given customer id.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterPatchAddress

afterPatchAddress (customer : Customer , addressName : String ) : Status

The function is called after updating an address of a customer.

Parameters:
customer - the customer for whom the address was updated
addressName - the name of the address which was updated
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforePatchAddress

beforePatchAddress (customer : Customer , addressName : String ) : Status

The function is called before updating an address of a customer.

Parameters:
customer - the customer for whom to update the address
addressName - the name of the address to be updated
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json

{
  "address_id" : "home_address",
  "address1" : "6 Wall St",
  "address2" : "26 Presidential Way",
  "city" : "Burlington",
  "company_name" : "Salesforce",
  "country_code" : "US",
  "first_name": "John",
  "job_title" : "Developer",
  "last_name" : "Murphy",
  "phone" : "408-555-1212",
  "postal_code" : "01805",
  "post_box" : "12b",
  "preferred" : false,
  "salutation" : "Mr.",
  "second_name" : "Jim",
  "state_code": "MA",
  "title": "Dr."
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220

{
   "_v" : "16.2",
   "_type" : "customer_address",
   "address1" : "6 Wall St",
   "address2" : "26 Presidential Way",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce",
   "country_code" : "US",
   "first_name" : "John",
   "full_name" : "John Jim Murphy",
   "job_title" : "Developer",
   "last_name" : "Murphy",
   "phone" : "408-555-1212",
   "postal_code" : "01805",
   "post_box" : "12b",
   "preferred" : false,
   "salutation" : "Mr.",
   "second_name" : "Jim",
   "state_code" : "MA",
   "title" : "Dr."
}

# in case of validation failure - example response in case of attempt to update non-existing address:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "Customer address 'home_address' not found."
   }
}

REQUEST:
PATCH /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json

{
  "address_id" : "old_home_address",
}

# in case of success:

RESPONSE:
HTTP/1.1 301 MOVED PERMANENTLY
Location: /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/old_home_address
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220

{
   "_v" : "16.2",
   "_type" : "customer_address",
   "address1" : "6 Wall St",
   "address2" : "26 Presidential Way",
   "address_id" : "old_home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce",
   "country_code" : "US",
   "first_name" : "John",
   "full_name" : "John Jim Murphy",
   "job_title" : "Developer",
   "last_name" : "Murphy",
   "phone" : "408-555-1212",
   "postal_code" : "01805",
   "post_box" : "12b",
   "preferred" : false,
   "salutation" : "Mr.",
   "second_name" : "Jim",
   "state_code" : "MA",
   "title" : "Dr."
}

Get Basket

Gets the baskets of a customer.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/baskets

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

BasketsResult

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer to retrieve the baskets for minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   if customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Sample

# Request

REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/baskets?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json;charset=UTF-8

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "baskets_result",
   "baskets" : 
   [
      {
         "_type" : "basket",
          "basket_id" : "bccO1aOjgEnuIaaadk7pYO2rFE",
 ...      
      },
      
      {
         "_type" : "basket",
         "basket_id" : "bcs5vaOjgEQ9Uaaadk9zQIrXE6",
...            
      }
   ],
   "total" : 2
}

Get Orders of Customer

Returns a pageable list of all customer's orders. The default page size is 10.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/orders?start={Integer}&count={Integer}&cross-sites={Boolean}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

CustomerOrderResult

Path Parameters

Parameter Type Description Constraints
customer_id String the customer uuid minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer the maximum number of instances per request; default value is 10 maxIntegerValue=200, minIntegerValue=1
cross-sites Boolean the flag whether all sites should be searched; ignored in case of JWT; default value is false  
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
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Sample

# Request, no paging details

REQUEST:
GET /dw/shop/v16_2/customers/cevGs1bS2Xac8fpwe6GHJEzYlg/orders?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json

# Request, with paging details

REQUEST:
GET /dw/shop/v16_2/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?start=0&count=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json


# in case of success
# note: "next" and / or "previous" links only exist when appropriate, and only if paging details were provided

RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer_order_result",
   "count" : 1,
   "data" : 
   [
      
      {
         "_type" : "order",
         "adjusted_merchandize_total_tax" : 5.00,
         "adjusted_shipping_total_tax" : 0.00,
         ...
         "customer_info" : 
         {
            "_type" : "customer_info",
            "customer_id" : "bczhcasxVFpLdxtF05OIPEb25u",
            "customer_name" : "John Smith",
            "email" : "[email protected]"
         },
         ...
         "order_no" : "00001228",
         ...
         "payment_instruments" : 
         [
         ...            
         ],
         "product_items" : 
         [
         ...            
         ],
         "product_sub_total" : 16.29,
         "product_total" : 16.29,
         "shipments" : 
         [
         ...
         ],
         "shipping_items" : 
         [
         ...
         ],
         "shipping_total" : 0.01,
         "shipping_total_tax" : 0.00,
         "status" : "created",
         "taxation" : "net",
         "tax_total" : 5.00,
         ...
      }
   ],
   "next" : "https://.../.../.../dw/shop/v16_2/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?count=1&start=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "start" : 0,
   "total" : 3
}


# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Updates a Customer's Password.

Updates the customer's password.

Url

PUT https://hostname:port/dw/shop/v16_2/customers/{customer_id}/password

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.

Request Document

PasswordChangeRequest

Path Parameters

Parameter Type Description Constraints
customer_id String the customer id minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.putPassword

putPassword (customer : Customer , passwordChangeRequest : PasswordChangeRequest ) : Status

The function is called to update a customer's password. Use custom implementation to change password e.g. in third party systems. The default implementation will try to change the authenticated user password with the new password provided in the request. In case of an error the default implementation will return the error statuses listed in {@link dw.customer.Credentials#setPassword(String, String, boolean)}.

Parameters:
customer - the customer to be updated
passwordChangeRequest - the input containing the old and new passwords
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/password
Host: example.com
Authorization: Bearer eyJfdiI6IjEiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXUy.....
Content-Type: application/json

{"current_password": "01dpass", "password": "newpass"}

# in case of success:

RESPONSE:
HTTP/1.1 204 NO CONTENT


#example response in case of an empty new password:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "arguments" : 
      {
         "extensionPoint" : "dw.ocapi.shop.customer.putPassword",
         "statusCode" : "The new password is empty.",
         "statusMessage" : "The new password is empty."
      },
      "type" : "HookStatusException",
      "message" : "Error in ExtensionPoint 'dw.ocapi.shop.customer.putPassword'!"
   }
}

Starts a Password Reset Process

Starts a password reset process. A password reset token is generated and passed together with the customer resolved by the id provided as path parameter to a afterPOST hook. The hook dw.ocapi.shop.customer.password_reset.afterPOST can utilize the provided reset token, for example to send a reset email.

Url

POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/password_reset

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer specified was not found.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.password_reset.afterPOST

afterPOST (customer : Customer , resetToken : String ) : Status

Allows resetting a customer password. See the example below sending an email with a password reset link. 
 var variables: Map = new dw.util.HashMap();
 variables.put("Customer", customer);
 variables.put("ResetPasswordToken", token);
 var template: Template = new dw.util.Template("mail/resetpasswordemail.isml");
 var content: MimeEncodedText = template.render(variables);
 var mail: Mail = new Mail().setSubject("Password Reset").setContent(content).setFrom("[email protected]").addTo(customer.profile.email);
 mail.send();
Parameters:
customer - the customer for whom to reset the password
resetToken - the token generated by the system to be used for the reset
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v16_2/customers/cdRXAiWbPdMhcaaadh5hZczLu5/password_reset
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

# in case of success:

RESPONSE:
HTTP/1.1 204 NO CONTENT

# in case of password reset failure in hook dw.ocapi.shop.customer.password_reset.afterPOST.
# The wrong status with code and message is returned by the custom code.

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "fault" : 
   {
      "arguments" : 
      {
         "extensionPoint" : "dw.ocapi.shop.customer.password_reset.afterPOST",
         "statusCode" : "EXT_PW_CHANGE_FAIL",
         "statusMessage" : "Password reset not successful in external system."
      },
      "type" : "HookStatusException",
      "message" : "Error in ExtensionPoint 'dw.ocapi.shop.customer.password_reset.afterPOST'!"
   }
}

Get Customer Payment Instruments

Gets customer payment instruments for an customer.

Can be limited to a specific payment method by providing query parameter payment_method_id.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments?payment_method_id={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

CustomerPaymentInstrumentResult

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer to retrieve the payment instruments for minLength=1

Query Parameters

Parameter Type Description Constraints
payment_method_id String the id of the payment method, if null - all payment instruments are retrieved  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Sample

REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer_payment_instrument_result",
   "count" : 2,
   "data" : 
   [
      
      {
         "_type" : "customer_payment_instrument",
         "payment_bank_account" : 
         {
            "_type" : "payment_bank_account"
         },
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "John Doe",
            "masked_number" : "***********1111",
            "number_last_digits" : "1111"
         },
         "payment_method_id" : "CREDIT_CARD",
         "payment_instrument_id" : "cdlPgiWbN6LM2aaadkcia6MgbA",
         "c_strValue" : "custom value 2"
      },
      
      {
         "_type" : "customer_payment_instrument",
         "bank_routing_number" : "bankrouting3446",
         "gift_certificate_code_masked" : "*****code",
         "payment_bank_account" : 
         {
            "_type" : "payment_bank_account",
            "drivers_license_last_digits" : "e111",
            "drivers_license_state_code" : "MA",
            "holder" : "Joe Doe",
            "masked_drivers_license" : "**********e111",
            "masked_number" : "**********t111",
            "number_last_digits" : "t111"
         },
         "payment_card" : 
         {
            "_type" : "payment_card",
            "credit_card_expired" : false
         },
         "payment_method_id" : "OCAPI_Payment_Simple",
         "payment_instrument_id" : "cdTsgiWbN6DFEaaadkbia6MgbA",
         "c_strValue" : "custom value 1"
      }
   ],
   "total" : 2
}

# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Add Payment Instrument for Customer

Adds a payment instrument to a customer information.

Url

POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

CustomerPaymentInstrumentRequest

Response Document

CustomerPaymentInstrument

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterPostPaymentInstrument

afterPostPaymentInstrument (customer : Customer , paymentInstrument : CustomerPaymentInstrumentRequest ) : Status

The function is called after a payment instrument was added to a customer.

Parameters:
customer - the customer for whom to add the payment instrument
paymentInstrument - the payment instrument which was added
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforePostPaymentInstrument

beforePostPaymentInstrument (customer : Customer , paymentInstrument : CustomerPaymentInstrumentRequest ) : Status

The function is called before a payment instrument is added to a customer.

Parameters:
customer - the customer for whom to add the payment instrument
paymentInstrument - the payment instrument to be added
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json; charset=UTF-8
{
  "payment_card":{
                   "expiration_year":2027,
                   "expiration_month":7,
                   "valid_from_month":8,
                   "valid_from_year":2007,
                   "issue_number":"i117",
                   "number":"1234567",
                   "holder":"Joe Doe",
                   "card_type":"MasterCard"
                  },
  "gift_certificate_code": "gift_code7",
  "payment_method_id": "OCAPI_Payment_Simple",
  "bank_routing_number":"bankrouting3776",
  "c_strValue":"custom value 7"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "_type" : "customer_payment_instrument",
   "bank_routing_number" : "bankrouting3776",
   "gift_certificate_code_masked" : "******ode7",
   "payment_bank_account" : 
   {
      "_type" : "payment_bank_account"
   },
   "payment_card" : 
   {
      "_type" : "payment_card",
      "card_type" : "MasterCard",
      "credit_card_expired" : false,
      "expiration_month" : 7,
      "expiration_year" : 2027,
      "holder" : "Joe Doe",
      "issue_number" : "i117",
      "masked_number" : "***4567",
      "number_last_digits" : "4567",
      "valid_from_month" : 8,
      "valid_from_year" : 2007
   },
   "payment_method_id" : "OCAPI_Payment_Simple",
   "payment_instrument_id" : "cdOLciWbOsYl6aaadkwcsx9xHH",
   "c_strValue" : "custom value 7"
}


# in case of validation failure - example response when the customer is not found:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "No customer with id 'acE9xUWs5ea75qwTh0Svi2XfRY' found."
   }
}

Get Customer Payment Instrument

Retrieves a customer's payment instrument by its id.

Url

GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

CustomerPaymentInstrument

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer to retrieve the payment instrument for minLength=1
payment_instrument_id String the id of the payment instrument to be retrieved minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

 Indicates that the payment instrument with the given id is unknown for the customer with the given customer id.

Sample

REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/eg5hEiWbPdcaQaaaekty3fqx1o
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "customer_payment_instrument",
   "payment_bank_account" : 
   {
      "_type" : "payment_bank_account"
   },
   "payment_card" : 
   {
      "_type" : "payment_card",
      "card_type" : "Visa",
      "credit_card_expired" : false,
      "expiration_month" : 3,
      "expiration_year" : 2023,
      "holder" : "John Doe",
      "masked_number" : "***********1111",
      "number_last_digits" : "1111"
   },
   "payment_method_id" : "CREDIT_CARD",
   "payment_instrument_id" : "eg5hEiWbPdcaQaaaekty3fqx1o",
   "c_strValue" : "custom Test value 3"
}

# in case of validation failure - example response in case of unknown customer payment intrument:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "The payment instrument with uuid 'cdmh6iWbObcXUaaadkPA7ydxnr' was not found."
   }
}

Delete Customer Payment Instrument

Deletes a customer's payment instrument.

Url

DELETE https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
customer_id String the id of the customer to delete the payment instrument for minLength=1
payment_instrument_id String the id of the payment instrument to be deleted minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 CustomerNotFoundException

customerId (String)

 Indicates that the customer with the given customer id is unknown for the site.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.afterDeletePaymentInstrument

afterDeletePaymentInstrument (customer : Customer , paymentInstrumentId : String ) : Status

The function is called after removing a payment instrument of a customer.

Parameters:
customer - the customer for whom to delete the payment instrument
paymentInstrumentId - the id of the payment instrument which was deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.beforeDeletePaymentInstrument

beforeDeletePaymentInstrument (customer : Customer , paymentInstrumentId : String ) : Status

The function is called before removing a payment instrument of a customer.

Parameters:
customer - the customer for whom to delete the payment instrument
paymentInstrumentId - the id of the payment instrument to be deleted
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/cdmh6iWbObcXUaaadkPA7ydxnr
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 204 NO CONTENT


# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:

RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

© Copyright 2000-2020, salesforce.com inc. All rights reserved. Various trademarks held by their respective owners.

 Show URL Submit FeedbackPrivacy Policy
OCAPI obsolete versions 13.x and 14.x will be end of life in 2020 and versions 15.x and 16.x in 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.