Customers resource (Shop API 19.5)

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.

DELETE /customers/auth Invalidates the JWT provided in the header.
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 First the beforePOST hook is called. After that the validation of the customer information provided in the the password reset document is performed. Then 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. Both hooks are performed in a single transaction. 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.

When the customer cannot be found CustomerNotFoundException is thrown in a case of an agent but an empty result list is returned in a case of JWT.
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.
POST /customers/{customer_id}/auth

Obtains a new agent on behalf token for a registered customer. Token is returned as a HTTP Authorization:Bearer response header entry.

A token is created and returned to the client whenever an agent with Create_Order_On_Behalf_Of permission calls the resource for a registered customer.

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 agent will do on behalf of the customer.

About the order on behalf token

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 nearing its expiration time should be exchanged for a new one by calling this resource once more.

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.

When the customer cannot be found CustomerNotFoundException is thrown in a case of an agent but an empty result list is returned in a case of JWT.
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.
GET /customers/{customer_id}/product_lists Returns all customer product lists.
POST /customers/{customer_id}/product_lists Creates a customer product list.
GET /customers/{customer_id}/product_lists/{list_id} Returns a customer product list of the given customer.
PATCH /customers/{customer_id}/product_lists/{list_id} Changes a product list. Changeable properties are the name, description and if the list is public.
DELETE /customers/{customer_id}/product_lists/{list_id} Deletes a customer product list.
GET /customers/{customer_id}/product_lists/{list_id}/items Returns a pageable list of all items of a customer's product list. The default page size is 10.
POST /customers/{customer_id}/product_lists/{list_id}/items Adds an item to the customer's product list. Considered values from the request body are:
  • type: a valid type, mandatory. This is the type of the item to be added to the customer's product list.
  • priority: This is the priority of the item to be added to the customer's product list.
  • public: This is the flag whether the item to be added to the customer's product list is public.
  • product_id: a valid product id, used for product item type only. This is the id (sku) of the product related to the item to be added to the customer's product list. It is mandatory for product item type and it must be a valid product id, otherwise ProductListProductIdMissingException or ProductListProductNotFoundException will be thrown.
  • quantity: used for product item type only. This is the quantity of the item to be added to the customer's product list.
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductListItem. The value of this property must be valid for the type of custom attribute defined for ProductListItem.
GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id} Returns an item of a customer product list.
DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id} Removes an item from a customer product list.
PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id} Updates an item of a customer's product list. Considered values from the request body are:
  • priority: This is the priority of the customer's product list item.
  • public: This is the flag whether the customer's product list item is public.
  • quantity: used for product item type only. This is the quantity of the customer's product list item.
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductListItem. The value of this property must be valid for the type of custom attribute defined for ProductListItem.
GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases Returns a list of all purchases of an item from a customer's product list.
POST /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases Adds a purchase to an item in the customer's product list. Considered values from the request body are:
  • purchaser_name: name of the purchaser, mandatory. This is the full name of the purchaser of this product list item.
  • quantity: amount purchased, mandatory. This is the quantity of the items purchased from the product list.
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductListItemPurchase. The value of this property must be valid for the type of custom attribute defined for ProductListItemPurchase.
GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id} Returns a purchase of an item from a customer's product list.
PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id} Updates a purchase of an item from a customer's product list. Considered values from the request body are:
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductListItemPurchase. The value of this property must be valid for the type of custom attribute defined for ProductListItemPurchase.

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/v19_5/customers

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
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
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.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , customerResponse : Customer ) : Status

Parameters:
customer - created customer
customerResponse - customer response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers HTTP/1.1
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "19.5",
   "fault" : 
   {
      "type" : "LoginAlreadyInUseException",
      "message" : "The login is already in use."
   }
}

Invalidate an existing customer JWT (JSON Web Token)

Invalidates the JWT provided in the header.

Url

DELETE https://hostname:port/dw/shop/v19_5/customers/auth

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.

Header Parameters

Parameter Type Description Constraints
Authorization String the JWT token  

Sample

# Request JWT invalidation for the provided token

REQUEST:
DELETE /dw/shop/v19_5/customers/auth HTTP/1.1
Host: example.com
Authorization:Bearer <<token>> 
Content-Type:application/json

# in case of success, the token will be invalidated

RESPONSE:
HTTP/1.1 204 OK
Content-Length:0

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/v19_5/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.beforePOST

beforePOST (authorizationHeader : String , authRequestType : EnumValue ) : Status

The function is called before the customer has been authenticated.

Parameters:
authorizationHeader - the authorization header. Differs depending on the type:
  • guest - no content relevant to the authentication.
  • credentials - Base64 encoded username and password. For example Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. It is possible to extract the username or password:
    
           var credentials = authHeader.substr(6);
           // cut out Basic
           var base64decoded : String = StringUtils.decodeBase64(credentials, "UTF-8");
           var userName : String = base64decoded.split(":")[0];
           var password : String = base64decoded.split(":")[1];
           
  • refresh - A refresh token, for example Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX
  • session - no content relevant to the authentication. Authentication based on cookies.
authRequestType - does the request specify a guest, login or refresh authentication
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.auth.afterPOST

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

The function is called after the customer has been authenticated.

Parameters:
customer - the authenticated customer
authRequestType - does the request specify a guest, login or refresh authentication
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.auth.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , customerResponse : Customer , authRequestType : EnumValue ) : Status

Parameters:
customer - the auth customer
customerResponse - customer response object
authRequestType - auth request type enum
Returns:
a non-null Status ends the hook execution

Sample

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

REQUEST:
POST /dw/shop/v19_5/customers/auth HTTP/1.1
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/v19_5/customers/auth HTTP/1.1
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/v19_5/customers/auth HTTP/1.1
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/v19_5/customers/auth HTTP/1.1
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" : "19.5",
   "_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" : "19.5",
   "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" : "19.5",
   "fault" : 
   {
      "type" : "AuthorizationBasicMissingException",
      "message" : "Missing credentials: Add an 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" : "19.5",
   "fault" : 
   {
      "type" : "AuthenticationFailedException",
      "message" : "Customer authentication based on Authorization:Basic header failed.
   }
}

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

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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "AuthenticationFailedException",
      "message" : "Customer authentication based on session failed.
   }
}

Starts a password reset process

First the beforePOST hook is called. After that the validation of the customer information provided in the the password reset document is performed. Then 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. Both hooks are performed in a single transaction. 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/v19_5/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.beforePOST

beforePOST (passwordReset : PasswordReset ) : Status

Allows resetting a customers password. The validation of the customer information provided in the the password reset document is done after this hook is called.

Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customers.password_reset.afterPOST

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

Allows resetting a customers 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/v19_5/customers/password_reset HTTP/1.1
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" : "19.5",
   "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/v19_5/customers/{customer_id}?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.

Customization

This Resource supports server-side customization.

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

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - The customer id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.modifyGETResponse

modifyGETResponse (customer : Customer , customerResponse : Customer ) : Status

Parameters:
customer - target customer
customerResponse - customer response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/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
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "01827",
         "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":"19.5",
  "_type":"fault",
  "fault":{
    "type":"InvalidCustomerException",
    "message":"Invalid customer."
  }
}

Updates a customer

Updates a customer.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

Customer

Response Document

Customer

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.
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.beforePATCH

beforePATCH (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
dw.ocapi.shop.customer.afterPATCH

afterPATCH (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.modifyGETResponse

modifyGETResponse (customer : Customer , customerResponse : Customer ) : Status

Parameters:
customer - target customer
customerResponse - customer response object
Returns:
a non-null Status ends the hook execution

Sample

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

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "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.

When the customer cannot be found CustomerNotFoundException is thrown in a case of an agent but an empty result list is returned in a case of JWT.

Url

GET https://hostname:port/dw/shop/v19_5/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. A valid user is required.

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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.addresses.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.addresses.modifyGETResponse

modifyGETResponse (customerAddressResultResponse : CustomerAddressResult ) : Status

Parameters:
customerAddressResultResponse - customer addresses result response
Returns:
a non-null Status ends the hook execution

Sample

# Request, no paging details

REQUEST:
GET /dw/shop/v19_5/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses HTTP/1.1
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/v19_5/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?start=0&count=1 HTTP/1.1
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" : "19.5",
   "_type" : "customer_address_result",
   "count" : 1,
   "data" : 
   [
      {
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "_type" : "customer_address",
         "address1" : "10 Free Way",
         "address_id" : "private",
         "city" : "Woburn",
         "country_code" : "US",
         "first_name" : "James",
         "full_name" : "James Last",
         "last_name" : "Last",
         "postal_code" : "01827",
         "salutation" : "Mr.",
         "state_code" : "MA"
      }
   ],
   "next" : "https://example.com/dw/shop/v19_5/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?count=1&start=1",
   "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/v19_5/customers/{customer_id}/addresses

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.addresses.beforePOST

beforePOST (customer : Customer , addressName : String , customerAddress : CustomerAddress ) : 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
customerAddress - the customer address request data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.addresses.afterPOST

afterPOST (customer : Customer , addressName : String , customerAddress : CustomerAddress ) : 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
customerAddress - the customer address request data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.addresses.modifyGETResponse

modifyGETResponse (customerAddressResultResponse : CustomerAddressResult ) : Status

Parameters:
customerAddressResultResponse - customer addresses result response
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses HTTP/1.1
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 Commerce Cloud",
  "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
{
   "_v" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "customer_address",
   "address1" : "5 Wall St",
   "address2" : "24 Presidential Way",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce Commerce Cloud",
   "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" : "19.5",
   "fault" : 
   {
      "type" : "AddressNameAlreadyInUseException",
      "message" : "The customer address name is already in use."
   }
}

Get customer address

Retrieves a customer's address by address name.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.address.beforeGET

beforeGET (customerId : String , addressName : String ) : Status

The function is called before the request will be processed.

Parameters:
customer - target customer
customerAddress - target customer address
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.address.modifyGETResponse

modifyGETResponse (customer : Customer , customerAddress : CustomerAddress , customerAddressResponse : CustomerAddress ) : Status

Parameters:
customer - target customer
customerAddress - target customer address
customerAddressResponse - customer address response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address HTTP/1.1
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" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "customer_address",
   "address1" : "5 Wall St",
   "address2" : "24 Presidential Way",
   "address_id" : "59aed97608cf7f72",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce Commerce Cloud",
   "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" : "19.5",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "The customer address 'home_address' could not be found."
   }
}

Delete customer address

Deletes a customer's address by address name.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.address.beforeDELETE

beforeDELETE (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
dw.ocapi.shop.customer.address.afterDELETE

afterDELETE (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

Sample

REQUEST:
DELETE /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# 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" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Update customer address

Updates a customer's address by address name.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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

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.address.beforePATCH

beforePATCH (customer : Customer , addressName : String , customerAddress : CustomerAddress ) : 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
customerAddress - the customer address request data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.address.afterPATCH

afterPATCH (customer : Customer , addressName : String , customerAddress : CustomerAddress ) : 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
customerAddress - the customer address request data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.address.modifyPATCHResponse

modifyPATCHResponse (customer : Customer , customerAddress : CustomerAddress , customerAddressResponse : CustomerAddress , customerAddressRequest : CustomerAddress ) : Status

Parameters:
customerAddress - target customer address
customerAddressResponse - customer address response object
customerAddressRequest - customer address request object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "address_id" : "home_address",
  "address1" : "6 Wall St",
  "address2" : "26 Presidential Way",
  "city" : "Burlington",
  "company_name" : "Salesforce Commerce Cloud",
  "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
{
   "_v" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "customer_address",
   "address1" : "6 Wall St",
   "address2" : "26 Presidential Way",
   "address_id" : "home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce Commerce Cloud",
   "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" : "19.5",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "Customer address 'home_address' not found."
   }
}

REQUEST:
PATCH /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "address_id" : "old_home_address",
}

# in case of success:

RESPONSE:
HTTP/1.1 301 MOVED PERMANENTLY
Location: /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/old_home_address
Content-Type: application/json;charset=UTF-8
{
   "_v" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "customer_address",
   "address1" : "6 Wall St",
   "address2" : "26 Presidential Way",
   "address_id" : "old_home_address",
   "city" : "Burlington",
   "company_name" : "Salesforce Commerce Cloud",
   "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 an agent on behalf of customer token

Obtains a new agent on behalf token for a registered customer. Token is returned as a HTTP Authorization:Bearer response header entry.

A token is created and returned to the client whenever an agent with Create_Order_On_Behalf_Of permission calls the resource for a registered customer.

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 agent will do on behalf of the customer.

About the order on behalf token

The token contains 3 sections:

A token nearing its expiration time should be exchanged for a new one by calling this resource once more.

Url

POST https://hostname:port/dw/shop/v19_5/customers/{customer_id}/auth

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token. A valid user is required.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

Customer

Path Parameters

Parameter Type Description Constraints
customer_id String specifies the customer to act on behalf of minLength=1

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.auth.beforePOST

beforePOST (customer : Customer ) : Status

The function is called before the customer has been authenticated.

Parameters:
customer - the customer that is authenticated
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.auth.afterPOST

afterPOST (customer : Customer ) : Status

The function is called after the customer has been authenticated.

Parameters:
customer - the customer that is authenticated
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.auth.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , customerResponse : Customer ) : Status

Parameters:
customer - target customer
customerResponse - customer response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/acI4Lg0fMrBZ6shBanPpvkIKHZ/auth HTTP/1.1
Host: example.com
Authorization: Bearer 26b89022-d8e2-4399-8b78-b3304aa3af3e
Content-Length: 0

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

{
   "_v" : "19.5",
   "_type" : "customer",
   "auth_type" : "registered",
   "creation_date" : "2012-03-30T08:23:51.000Z",
   "customer_id" : "acI4Lg0fMrBZ6shBanPpvkIKHZ",
   "customer_no" : "00001140",
   "email" : "[email protected]",
   "enabled" : true,
   "first_name" : "John",
   "gender" : 1,
   "last_login_time" : "2012-04-05T06:08:38.000Z",
   "last_name" : "Doe",
   "last_visit_time" : "2012-04-05T06:08:38.000Z",
   "login" : "johndoe",
   "previous_login_time" : "2012-04-05T06:08:38.000Z",
   "previous_visit_time" : "2012-04-05T06:08:38.000Z",
}

Get basket

Gets the baskets of a customer.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.baskets.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the baskets result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.baskets.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , customerBasketsResultResponse : BasketsResult ) : Status

Parameters:
customer - the customer the baskets result retrieved for.
customerBasketsResultResponse - customer basket result response object
Returns:
a non-null Status ends the hook execution

Sample

# Request

REQUEST:
GET /dw/shop/v19_5/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/baskets 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

{
   "_v" : "19.5",
   "_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/v19_5/customers/{customer_id}/orders?start={Integer}&count={Integer}&cross-sites={Boolean}&from={String}&until={String}&status={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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  
from String The from date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).  
start Integer the result set index to return the first instance for; default value is 0 minIntegerValue=0
status String The order status of the orders to be retrieved. Status included: created, new, open, completed, cancelled, replaced, failed.  
until String The until date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).  

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 InvalidOrderStatusException

status (String)

Thrown if specified status 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.orders.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the orders are retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.orders.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , customerOrderResultResponse : CustomerOrderResult ) : Status

Parameters:
customer - the customer the orders are retrieved for.
customerOrderResultResponse - customer order result response object
Returns:
a non-null Status ends the hook execution

Sample

# Request, no paging details

REQUEST:
GET /dw/shop/v19_5/customers/cevGs1bS2Xac8fpwe6GHJEzYlg/orders HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type:application/json

# Request, with paging details

REQUEST:
GET /dw/shop/v19_5/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?start=0&count=1 HTTP/1.1
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" : "19.5",
   "_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.49,
         "product_total" : 16.49,
         "shipments" : 
         [
         ...
         ],
         "shipping_items" : 
         [
         ...
         ],
         "shipping_total" : 0.01,
         "shipping_total_tax" : 0.00,
         "status" : "created",
         "taxation" : "net",
         "tax_total" : 5.00,
         ...
      }
   ],
   "next" : "https://example.com/dw/shop/v19_5/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?count=1&start=1",
   "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" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Updates a customer's password.

Updates the customer's password.

Url

PUT https://hostname:port/dw/shop/v19_5/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.password.beforePUT

beforePUT (customerId : String ) : 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:
customerId - the customer id to be updated
passwordChangeRequest - the input containing the old and new passwords
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.password.afterPUT

afterPUT (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 /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/password HTTP/1.1
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" : "19.5",
   "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/v19_5/customers/{customer_id}/password_reset

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token. A valid user is required.
OAuth Authentication via OAuth token. A valid user is required.

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.beforePOST

beforePOST (customer : Customer ) : Status

The function is called before the request will be processed.

Parameters:
customer - the customer for whom to reset the password
Returns:
a non-null Status ends the hook execution
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:
POST /dw/shop/v19_5/customers/cdRXAiWbPdMhcaaadh5hZczLu5/password_reset HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Length: 0

# 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" : "19.5",
   "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.

When the customer cannot be found CustomerNotFoundException is thrown in a case of an agent but an empty result list is returned in a case of JWT.

Url

GET https://hostname:port/dw/shop/v19_5/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. A valid user is required.

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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.payment_instruments.beforeGET

beforeGET (customerId : String , paymentMethodId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the customer payment instruments result retrieved for.
paymentMethodId - the id of the payment method, if null - all payment instruments are retrieved
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.payment_instruments.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , customerPaymentInstrumentResultResponse : CustomerPaymentInstrumentResult ) : Status

Parameters:
customer - the customer the customer payment instruments result retrieved for.
customerPaymentInstrumentResultResponse - customer payment instrument result response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments HTTP/1.1
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" : "19.5",
   "_type" : "customer_payment_instrument_result",
   "count" : 2,
   "data" : 
   [
      
      {
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "_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"
      },
      
      {
         "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "_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" : "19.5",
   "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/v19_5/customers/{customer_id}/payment_instruments

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

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.payment_instrument.beforePOST

beforePOST (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
dw.ocapi.shop.customer.payment_instrument.afterPOST

afterPOST (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.payment_instrument.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , customerPaymentInstrument : CustomerPaymentInstrument , customerPaymentInstrumentResponse : CustomerPaymentInstrument ) : Status

Parameters:
Customer - target customer
customerPaymentInstrument - payment instrument
customerPaymentInstrumentResponse - customer payment instrument response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments HTTP/1.1
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" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "19.5",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "No customer with ID 'acE9xUWs5ea75qwTh0Svi2XfRY' was found."
   }
}

Get customer payment instrument

Retrieves a customer's payment instrument by its id.

Url

GET https://hostname:port/dw/shop/v19_5/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. A valid user is required.

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 retrievedCustomer minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
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.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.payment_instrument.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - target customer id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.payment_instrument.modifyGETResponse

modifyGETResponse (customer : Customer , customerPaymentInstrument : CustomerPaymentInstrument , customerPaymentInstrumentResponse : CustomerPaymentInstrument ) : Status

Parameters:
customer - target customer
customerPaymentInstrument - payment instrument
customerPaymentInstrumentResponse - customer payment instrument response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/eg5hEiWbPdcaQaaaekty3fqx1o HTTP/1.1
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" : "19.5",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "19.5",
   "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/v19_5/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. A valid user is required.

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.payment_instrument.beforeDELETE

beforeDELETE (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
dw.ocapi.shop.customer.payment_instrument.afterDELETE

afterDELETE (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

Sample

REQUEST:
DELETE /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/cdmh6iWbObcXUaaadkPA7ydxnr HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# 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" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Get customer product lists

Returns all customer product lists.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductListResult

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 possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  

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.product_lists.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the customer product lists result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_lists.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , customerProductListResultResponse : CustomerProductListResult ) : Status

Parameters:
customer - the customer the customer product lists result retrieved for.
customerProductListResultResponse - customer product list result response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/abIc5hnebSnMSngHiQAekNE6Xd/product_lists HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_result",
   "count" : 1,
   "data" : 
   [
      {
         "_type" : "customer_product_list",
         "customer_product_list_items" : 
         [
            {
               "_type" : "customer_product_list_item",
               "id" : "30f35c187ea255ccb633c3ba11",
               "priority" : 4,
               "product_details_link" : 
               {
                  "_type" : "product_simple_link",
                  "link" : "https://example.com/dw/shop/v19_5/products/SimpleProduct",
                  "title" : "Image Product"
               },
               "product_id" : "SimpleProduct",
               "public" : false,
               "purchased_quantity" : 0,
               "quantity" : 2,
               "type" : "product",
               "c_intValue" : 7,
               "c_strValue" : "private product item"
            }
         ],
         "description" : "a productlist",
         "event" : 
         {
            "_type" : "product_list_event"
         },
         "id" : "8b04014a9d6e5dbae542004824",
         "items_link" : 
         {
            "_type" : "customer_product_list_item_link",
            "link" : "https://example.com/dw/shop/v19_5/customers/abIc5hnebSnMSngHiQAekNE6Xd/product_lists/8b04014a9d6e5dbae542004824/items",
            "title" : "1 items"
         },
         "public" : false,
         "type" : "wish_list"
      }
   ],
   "total" : 1
}


# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Create customer product list

Creates a customer product list.

Url

POST https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductList

Response Document

CustomerProductList

Path Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidAddressLinkException

addressId (String)

customerNo (String)

Indicates that the id of the given address link does not reference an address of the current customer.
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 InvalidProductListTypeException   Indicates that there was no or an invalid type given for the to be created product list.
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.product_lists.beforePOST

beforePOST (customer : Customer , productList : CustomerProductList ) : Status

The function is called before creating a new product list for the specified customer.

Parameters:
customer - the customer
productList - the product list to create
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_lists.afterPOST

afterPOST (customer : Customer , productList : CustomerProductList ) : Status

The function is called after creating a new product list for the specified customer.

Parameters:
customer - the customer
productList - the created product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , productList : ProductList , customerProductListResponse : CustomerProductList ) : Status

Parameters:
customer - target customer
productList - product list
customerProductListResponse - customer product list response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

{
    "type": "wish_list",
    "name": "OurProductList",
    "description": "our productlist",
    "public": false,
    "co_registrant" : 
    {
       "email" : "[email protected]",
       "first_name" : "Jane",
       "last_name" : "Doe",
       "role" : "Bride"
    },
    "registrant" : 
    {
       "email" : "[email protected]",
       "first_name" : "John",
       "last_name" : "Doe",
       "role" : "Groom"
    },
    "event" : 
    {
       "city" : "Washington",
       "country" : "US",
       "date" : "2015-07-30T00:00Z",
       "state" : "DC",
       "type" : "Wedding"
    }
}


# in case of success:

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

{
   "_v" : "19.5",
   "_type" : "customer_product_list",
   "_resource_state" : "c16d2a20fa9c1c52ca9de413dd430a335c50a1d4f1ccb3e020b25c8b90cee8b7",
   "co_registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "Jane",
      "last_name" : "Doe",
      "role" : "Bride"
   },
   "description" : "our productlist",
   "event" : 
   {
      "_type" : "product_list_event",
      "city" : "Washington",
      "country" : "US",
      "date" : "2015-07-30T00:00Z",
      "state" : "DC",
      "type" : "Wedding"
   },
   "id" : "bb151cd88655b081acc1fa85c6",
   "items_link" : 
   {
      "_type" : "customer_product_list_item_link",
      "link" : "https://example.com/dw/shop/v19_5/customers/abKvXV2tYXMZPTdDwPXgx031cd/product_lists/bb151cd88655b081acc1fa85c6/items",
      "title" : "0 items"
   },
   "name" : "OurProductList",
   "public" : false,
   "registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "John",
      "last_name" : "Doe",
      "role" : "Groom"
   },
   "type" : "wish_list"
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Get customer product list

Returns a customer product list of the given customer.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductList

Path Parameters

Parameter Type Description Constraints
customer_id String The customer id. mandatory=true, minLength=1, nullable=false
list_id String The product list id. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  

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 ProductListNotFoundException

productListId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.beforeGET

beforeGET (customerId : String , productListId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - The customer id.
productListId - The product list id.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.modifyGETResponse

modifyGETResponse (customer : Customer , productList : ProductList , customerProductListResponse : CustomerProductList ) : Status

Parameters:
customer - target customer
productList - target product list
customerProductListResponse - customer product list response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list",
   "co_registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "Jane",
      "last_name" : "Doe",
      "role" : "Bride"
   },
   "description" : "our productlist",
   "event" : 
   {
      "_type" : "product_list_event",
      "city" : "Washington",
      "country" : "US",
      "date" : "2015-07-30T00:00Z",
      "state" : "DC",
      "type" : "Wedding"
   },
   "id" : "bcedkiWbxCM2MaaadkRhB2IBzM",
   "items_link" : 
   {
      "_type" : "customer_product_list_item_link",
      "link" : "https://example.com/dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/items",
      "title" : "0 items"
   },
   "name" : "OurProductList",
   "public" : false,
   "registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "John",
      "last_name" : "Doe",
      "role" : "Groom"
   },
   "shipping_address_link" : 
   {
      "_type" : "address_link",
      "address_id" : "me",
      "link" : "https://example.com/dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/me",
      "title" : "me, John Doe, Woburn"
   },
   "type" : "wish_list"
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Change customer product list

Changes a product list. Changeable properties are the name, description and if the list is public.

Url

PATCH https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductList

Response Document

CustomerProductList

Path Parameters

Parameter Type Description Constraints
customer_id String The customer id. mandatory=true, minLength=1, nullable=false
list_id String The product list id. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.beforePATCH

beforePATCH (customer : Customer , productList : CustomerProductList ) : Status

The function is called before modifying a customer product list.

Parameters:
customer - the customer
productList - the product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.afterPATCH

afterPATCH (customer : Customer , productList : CustomerProductList ) : Status

The function is called after modifying a customer product list.

Parameters:
customer - the customer
productList - the product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.modifyPATCHResponse

modifyPATCHResponse (customer : Customer , productList : ProductList , customerProductListResponse : CustomerProductList ) : Status

Parameters:
customer - target customer
productList - target product list
customerProductListResponse - customer product list response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/cdmh6iWbObcXUaaadkPA7ydxnr HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
x-dw-resource-state:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json

{
    "description": "new description"
}


# in case of success:

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

{
   "_v" : "19.5",
   "_type" : "customer_product_list",
   "_resource_state" : "6a5813cf5afd5906b7f838379b597297123a7bc5208486cf08e4c31370669721",
   "co_registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "Jane",
      "last_name" : "Doe",
      "role" : "Bride"
   },
   "description" : "new description",
   "event" : 
   {
      "_type" : "product_list_event",
      "city" : "Washington",
      "country" : "US",
      "date" : "2015-07-30T00:00Z",
      "state" : "DC",
      "type" : "Wedding"
   },
   "id" : "cdmh6iWbObcXUaaadkPA7ydxnr",
   "items_link" : 
   {
      "_type" : "customer_product_list_item_link",
      "link" : "https://example.com/dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/cdmh6iWbObcXUaaadkPA7ydxnr/items",
      "title" : "0 items"
   },
   "name" : "OurProductList",
   "public" : false,
   "registrant" : 
   {
      "_type" : "product_list_registrant",
      "email" : "[email protected]",
      "first_name" : "John",
      "last_name" : "Doe",
      "role" : "Groom"
   },
   "shipping_address_link" : 
   {
      "_type" : "address_link",
      "address_id" : "me",
      "link" : "https://example.com/dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/me",
      "title" : "me, John Doe, Woburn"
   },
   "type" : "wish_list"
}


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

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
   "_v" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "cdmh6iWbObcXUaaadkPA7ydxnr"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'cdmh6iWbObcXUaaadkPA7ydxnr' was not found."
   }
}

Delete customer product list

Deletes a customer product list.

Url

DELETE https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Path Parameters

Parameter Type Description Constraints
customer_id String The customer id. mandatory=true, minLength=1, nullable=false
list_id String The product list id. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.beforeDELETE

beforeDELETE (customer : Customer , productList : ProductList ) : Status

The function is called before a customer product list is deleted.

Parameters:
customer - the customer
productList - the product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.afterDELETE

afterDELETE (customer : Customer , productListId : String ) : Status

The function is called after a customer product list is deleted.

Parameters:
customer - the customer
productListId - the product list id
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/cdmh6iWbObcXUaaadkPA7ydxnr HTTP/1.1
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" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Get items of customer's product list

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

Url

GET https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items?expand={String}&start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductListItemResult

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer to retrieve the product list items for. mandatory=true, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
count Integer The maximum number of instances per request; default value is 10. maxIntegerValue=200, minIntegerValue=1
expand String The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  
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.
404 ProductListNotFoundException

productListId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.items.beforeGET

beforeGET (customerId : String , productListId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the customer product list items result retrieved for.
productListId - the product list id the customer product list items result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.items.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , productList : ProductList , customerProductListItemResultResponse : CustomerProductListItemResult ) : Status

Parameters:
customer - the customer the customer product list items result retrieved for.
productList - the product list the customer product list items result retrieved for.
customerProductListItemResultResponse - customer product list item result response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/bdndMnaBvPR2v7xM04bEXaAqho/product_lists/a3c7975278be9a387e10db66f7/items HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item_result",
   "count" : 2,
   "data" : 
   [
      
      {
         "_type" : "customer_product_list_item",
         "_resource_state" : "73f63f1d95d3a9d5775c8bb678ec5f7704687829163f8e261c21436276da7da5",
         "id" : "ebe04a8c6be5c01a5dac9e50ac",
         "priority" : 4,
         "product_details_link" : 
         {
            "_type" : "product_simple_link",
            "link" : "https://example.com/dw/shop/v19_5/products/008884303989",
            "title" : "Platinum Blue Stripes Easy Care Fitted Shirt"
         },
         "product_id" : "008884303989",
         "public" : true,
         "purchased_quantity" : 0,
         "quantity" : 2,
         "type" : "product"
      },
      
      {
         "_type" : "customer_product_list_item",
         "_resource_state" : "72b19bb7f050da7921746cdbc6dff6774000ba6fdb473504389b5f457bbe9fc0",
         "id" : "f33bfc1a99e64c79ddfbb49b19",
         "priority" : 2,
         "public" : false,
         "purchased_quantity" : 0,
         "type" : "gift_certificate"
      }
   ],
   "start" : 0,
   "total" : 2
}

# in case of validation failure - example response in case of an unknown customer product list:

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" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "a3c7975278be9a387e10db66f7"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'a3c7975278be9a387e10db66f7' was not found."
   }
}

Add item to customer's product list

Adds an item to the customer's product list. Considered values from the request body are:

Url

POST https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductListItem

Response Document

CustomerProductListItem

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer - owner of the product list. mandatory=true, minLength=1, nullable=false
list_id String The id of the product list mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListItemTypeMissingException   Indicates that type property in request body is not provided.
400 ProductListProductIdMissingException   Indicates that product property in request body is not provided.
400 ProductListProductNotFoundException

productId (String)

Indicates that the product with the provided id is unknown.
400 ProductListDuplicateGiftCertificateException   Indicates that the customer product list already has gift certificate item.
404 CustomerNotFoundException

customerId (String)

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

productListId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.items.beforePOST

beforePOST (customer : Customer , productList : ProductList , item : CustomerProductListItem ) : Status

The function is called before adding an item to a customer product list.

Parameters:
customer - the customer
productList - the product list
item - the item to add to the customer product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.items.afterPOST

afterPOST (customer : Customer , productList : ProductList , item : CustomerProductListItem ) : Status

The function is called after adding an item to a customer product list.

Parameters:
customer - the customer
productList - the product list
item - the item added to the customer product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , productList : ProductList , customerProductListItemResponse : CustomerProductListItem , customerProductListItemRequest : CustomerProductListItem ) : Status

Parameters:
customer - target customer
productList - target product list
customerProductListItemResponse - customer product list item response object
customerProductListItemRequest - customer product list item request object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/bdndMnaBvPR2v7xM04bEXaAqho/product_lists/3590c1e6f1d58a050b3e2b33fc/items HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json

{ 
  "type": "product",
  "product_id" : "008884303989",
  "priority": 4,
  "quantity": 2,
  "public": true
}

# in case of success:

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

{
   "_v" : "19.5",
   "_type" : "customer_product_list_item",
   "_resource_state" : "826247114ce7f0afd37993890e05620b75fdacd09b2dad80406bba87926b91af",
   "id" : "1d447daa4d25805fd682bd4ce1",
   "priority" : 4,
   "product_details_link" : 
   {
      "_type" : "product_simple_link",
      "link" : "https://example.com/dw/shop/v19_5/products/008884303989",
      "title" : "Platinum Blue Stripes Easy Care Fitted Shirt"
   },
   "product_id" : "008884303989",
   "public" : true,
   "purchased_quantity" : 0,
   "quantity" : 2,
   "type" : "product"
}

# in case of validation failure - example response in case of an unknown customer product list:

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" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "a3c7975278be9a387e10db66f7"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'a3c7975278be9a387e10db66f7' was not found."
   }
}

Get an item of a customer product list

Returns an item of a customer product list.

Url

GET https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductListItem

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer to retrieve the product list items for. minLength=1
item_id String The id of the product list item to retrieve. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerNotFoundException

customerId (String)

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

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.beforeGET

beforeGET (customerId : String , productListId : String , productListItemId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - target customer id
productListId - the customers product list id the product list item purchase result retrieved for.
productListItemId - the product list id item the product list item purchase result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.modifyGETResponse

modifyGETResponse (customer : Customer , productListItem : ProductListItem , customerProductListItemResponse : CustomerProductListItem ) : Status

Parameters:
customer - target customer
productListItem - target product list item
customerProductListItemResponse - customer product list item response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/bdndMnaBvPR2v7xM04bEXaAqho/product_lists/307074e244c06058adfdccd786/items/17f6313d232767ef80da988a13 HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item",
   "id" : "17f6313d232767ef80da988a13",
   "priority" : 4,
   "product_details_link" : 
   {
      "_type" : "product_simple_link",
      "link" : "https://example.com/dw/shop/v19_5/products/008884303989",
      "title" : "Platinum Blue Stripes Easy Care Fitted Shirt"
   },
   "product_id" : "008884303989",
   "public" : true,
   "purchased_quantity" : 0,
   "quantity" : 2,
   "type" : "product"
}


# in case of validation failure - example response in case of an unknown customer product list:

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" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "a3c7975278be9a387e10db66f7"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'a3c7975278be9a387e10db66f7' was not found."
    }
}

Remove item from customer's product list

Removes an item from a customer product list.

Url

DELETE https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the owner of the product list minLength=1
item_id String The id of the product list item to delete. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerNotFoundException

customerId (String)

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

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.beforeDELETE

beforeDELETE (customer : Customer , productList : ProductList , item : ProductListItem ) : Status

The function is called before deleting an item from a customer product list.

Parameters:
customer - the customer
productList - the product list
item - the product list item to delete
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.afterDELETE

afterDELETE (customer : Customer , productList : ProductList , itemId : String ) : Status

The function is called after deleting an item from a customer product list.

Parameters:
customer - the customer
productList - the product list
itemId - the id of the deleted item
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v19_5/customers/bdndMnaBvPR2v7xM04bEXaAqho/product_lists/0f0cbd8584373da21e33dd9cd4/items/be99f1a857ad12fae8053eb0ab HTTP/1.1
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 an unknown customer product list:

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" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "a3c7975278be9a387e10db66f7"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'a3c7975278be9a387e10db66f7' was not found."
   }
}

Update customer's product list item

Updates an item of a customer's product list. Considered values from the request body are:

Url

PATCH https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductListItem

Response Document

CustomerProductListItem

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the owner of the product list. mandatory=true, minLength=1, nullable=false
item_id String The id of the product list item to update. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomerNotFoundException

customerId (String)

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

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.beforePATCH

beforePATCH (customer : Customer , productList : ProductList , item : CustomerProductListItem ) : Status

The function is called before updating an item of a customer product list.

Parameters:
customer - the customer
productList - the product list
item - the product list item to update
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.afterPATCH

afterPATCH (customer : Customer , productList : ProductList , item : CustomerProductListItem ) : Status

The function is called after updating an item of a customer product list.

Parameters:
customer - the customer
productList - the product list
item - the updated item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.modifyPATCHResponse

modifyPATCHResponse (customer : Customer , productList : ProductList , customerProductListItemResponse : CustomerProductListItem , customerProductListItemRequest : CustomerProductListItem ) : Status

Parameters:
customer - target customer
productList - target product list
customerProductListItemRequest - customer product list item request object
customerProductListItemResponse - customer product list item response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v19_5/customers/bdndMnaBvPR2v7xM04bEXaAqho/product_lists/5aa91dd24ef272a8318.74b812/items/1d447daa4d25805fd682bd4ce1 HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
x-dw-resource-state:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json

{
    "priority": 3,
    "quantity": 4,
    "public": false
}


# in case of success:

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

{
   "_v" : "19.5",
   "_type" : "customer_product_list_item",
   "_resource_state" : "826247114ce7f0afd37993890e05620b75fdacd09b2dad80406bba87926b91af",
   "id" : "1d447daa4d25805fd682bd4ce1",
   "priority" : 3,
   "product_details_link" : 
   {
      "_type" : "product_simple_link",
      "link" : "https://example.com/dw/shop/v19_5/products/008884303989",
      "title" : "Platinum Blue Stripes Easy Care Fitted Shirt"
   },
   "product_id" : "008884303989",
   "public" : false,
   "purchased_quantity" : 0,
   "quantity" : 4,
   "type" : "product"
}


# in case of validation failure - example response in case of an unknown customer product list:

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" : "19.5",
   "fault" : 
   {
      "arguments" : 
      {
         "productListId" : "a3c7975278be9a387e10db66f7"
      },
      "type" : "ProductListNotFoundException",
      "message" : "The product list with ID 'a3c7975278be9a387e10db66f7' was not found."
   }
}

Get the purchases of a customer product list item

Returns a list of all purchases of an item from a customer's product list.

Url

GET https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductListItemPurchaseResult

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer to retrieve the product list item purchases for. minLength=1
item_id String The id of the product list item to retrieve from. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.purchases.beforeGET

beforeGET (customerId : String , listId : String , itemId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - the customer id the product list item purchase result retrieved for.
listId - the customers product list id the product list item purchase result retrieved for.
itemId - the product list id item the product list item purchase result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchases.modifyGETResponse_v2

modifyGETResponse_v2 (customer : Customer , productList : ProductList , productListItem : ProductListItem , customerProductListItemPurchaseResultResponse : CustomerProductListItemPurchaseResult ) : Status

Parameters:
customer - the customer the product list item purchase result retrieved for.
productList - the customers product list the product list item purchase result retrieved for.
productListItem - the product list item the product list item purchase result retrieved for.
customerProductListItemPurchaseResultResponse - customer product list item purchase result response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/purchases HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item_purchase_result",
   "count" : 1,
   "data" : 
   [
      {
	     "_type" : "customer_product_list_item_purchase",
	     "id" : "2cebc21d3698a82efae72acff0",
	     "product_list_item_id" : "416ce013b346c908bee07d62e0",
	     "purchase_name" : "Jane Doe",
	     "quantity" : 1.0
      }
   ],
   "total" : 1
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Add a purchase to an item on a customer product list

Adds a purchase to an item in the customer's product list. Considered values from the request body are:

Url

POST https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductListItemPurchase

Response Document

CustomerProductListItemPurchase

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer - owner of the product list. minLength=1
item_id String The id of the product list item where to add the purchase. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.purchases.beforePOST

beforePOST (customer : Customer , productList : ProductList , productListItem : ProductListItem , purchase : CustomerProductListItemPurchase ) : Status

The function is called before adding a purchase to a customer product list item.

Parameters:
customer - the customer
productList - the product list
productListItem - the product list item
purchase - the purchase to add to the customer product list item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchases.afterPOST

afterPOST (customer : Customer , productList : ProductList , productListItem : ProductListItem , purchase : CustomerProductListItemPurchase ) : Status

The function is called after adding a purchase to a customer product list item.

Parameters:
customer - the customer
productList - the product list
productListItem - the product list item
purchase - the item added to the customer product list
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchases.modifyPOSTResponse

modifyPOSTResponse (customer : Customer , productList : ProductList , productListItem : ProductListItem , customerProductListItemPurchaseResponse : CustomerProductListItemPurchase , customerProductListItemPurchaseRequest : CustomerProductListItemPurchase ) : Status

Parameters:
customer - target customer
productList - target product list
productListItem - target product list item
customerProductListItemPurchaseResponse - customer product list item purchase response object
customerProductListItemPurchaseRequest - customer product list item purchase request object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/purchases HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item_purchase",
   "id" : "dcdb9e4d1f930a2d3a32310ec5",
   "product_list_item_id" : "842ea014e952ded367c74a6c56",
   "purchaser_name" : "first last",
   "quantity" : 1.0
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Get a purchase of a customer product list item

Returns a purchase of an item from a customer's product list.

Url

GET https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Response Document

CustomerProductListItemPurchase

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer to retrieve the product list items for. minLength=1
item_id String The id of the product list item to retrieve. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false
purchase_id String The id of the product list item purchase to retrieve. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
404 ProductListItemPurchaseNotFoundException

purchaseId (String)

Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.purchase.beforeGET

beforeGET (customerId : String ) : Status

The function is called before the request will be processed.

Parameters:
customerId - target customer id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchase.modifyGETResponse

modifyGETResponse (customer : Customer , productListItemPurchase : ProductListItemPurchase , customerProductListItemPurchaseResponse : CustomerProductListItemPurchase ) : Status

Parameters:
customer - target customer
productListItemPurchase - target product list item purchase
customerProductListItemPurchaseResponse - customer product list item purchase response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/purchases/83bc7410d26508b6c7598f3c24 HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item_purchase",
   "id" : "dcdb9e4d1f930a2d3a32310ec5",
   "product_list_item_id" : "842ea014e952ded367c74a6c56",
   "purchaser_name" : "first last",
   "quantity" : 1.0
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

Update a purchase of a customer product list item

Updates a purchase of an item from a customer's product list. Considered values from the request body are:

Url

PATCH https://hostname:port/dw/shop/v19_5/customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

CustomerProductListItemPurchase

Response Document

CustomerProductListItemPurchase

Path Parameters

Parameter Type Description Constraints
customer_id String The id of the customer to retrieve the product list item purchases for. minLength=1
item_id String The id of the product list item to retrieve. mandatory=true, maxLength=28, minLength=1, nullable=false
list_id String The id of the product list. mandatory=true, maxLength=28, minLength=1, nullable=false
purchase_id String The id of the product list item purchase to retrieve. mandatory=true, maxLength=28, minLength=1, nullable=false

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 ProductListNotFoundException

productListId (String)

Indicates that the product list with the given list id is unknown for the site and the customer.
404 ProductListItemNotFoundException

itemId (String)

Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
404 ProductListItemPurchaseNotFoundException

purchaseId (String)

Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.customer.product_list.item.purchase.beforePATCH

beforePATCH (customer : Customer , productList : ProductList , productListItem : ProductListItem , purchase : CustomerProductListItemPurchase ) : Status

The function is called before updating a purchase of a customer product list item.

Parameters:
customer - the customer
productList - the product list
productListItem - the product list item
purchase - the product list item purchase to update
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchase.afterPATCH

afterPATCH (customer : Customer , productList : ProductList , productListItem : ProductListItem , purchase : CustomerProductListItemPurchase ) : Status

The function is called after updating a purchase of a customer product list item.

Parameters:
customer - the customer
productList - the product list
productListItem - the product list item
purchase - the updated purchase
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.customer.product_list.item.purchase.modifyPATCHResponse

modifyPATCHResponse (customer : Customer , productList : ProductList , productListItem : ProductListItem , customerProductListItemPurchaseResponse : CustomerProductListItemPurchase , customerProductListItemPurchaseRequest : CustomerProductListItemPurchase ) : Status

Parameters:
customer - target customer
productList - target product list
productListItem - target product list item
customerProductListItemPurchaseRequest - customer product list item purchase request object
customerProductListItemPurchaseResponse - customer product list item purchase response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v19_5/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/purchases/83bc7410d26508b6c7598f3c24 HTTP/1.1
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" : "19.5",
   "_type" : "customer_product_list_item_purchase",
   "id" : "dcdb9e4d1f930a2d3a32310ec5",
   "product_list_item_id" : "842ea014e952ded367c74a6c56",
   "purchaser_name" : "first last",
   "quantity" : 1.0
}

# in case of validation failure - example response in case of an unknown 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

{
   "_v" : "19.5",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}