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
When using JWT the password is required. |
POST | /Customers/Auth | Obtains a new JWT (JSON Web Token) for a guest or
registered customer. Tokens are returned as a HTTP
Authorization:Bearer response header entry. These kinds of
request are supported, as specified by the
type :
About JWT The token contains 3 sections:
Authorization: Bearer --token--
The client has to include the token in
the request header as
Authorization: Bearer --token--
in any follow up request. The server
declines any follow up requests without a token or which cannot
be verified based on the token signature or expiration time. A
token nearing its expiration time should be exchanged for a new
one (type "refresh").
See "API
Usage > JWT" for more details on using JWT as an
authentication mechanism. |
POST | /Customers/Password_reset | Starts a password reset process. A password reset token is generated and together with the resolved customer is passed to a afterPOST hook. The customer resolution is based on the password reset request type. Currently the resolution can be done by email or login. In case of an email the password reset hook is only executed if one and only one customer has been identified for that email. In the case that more than one customers have been identified for the provided email the resource does nothing. |
GET | /Customers/{Customer_id} | Gets a customer. |
PATCH | /Customers/{Customer_id} | Updates a customer. |
GET | /Customers/{Customer_id}/Addresses | Returns a sorted pageable list of all customer addresses in the address book. The default page size is 10 customer addresses. The addresses are sorted so that the preferred address is always sorted first. The remaining addresses are sorted alphabetically by ID. |
POST | /Customers/{Customer_id}/Addresses | Creates a new address with the given name for the given customer. |
GET | /Customers/{Customer_id}/Addresses/{Address_name} | Retrieves a customer's address by address name. |
DELETE | /Customers/{Customer_id}/Addresses/{Address_name} | Deletes a customer's address by address name. |
PATCH | /Customers/{Customer_id}/Addresses/{Address_name} | Updates a customer's address by address name. |
GET | /Customers/{Customer_id}/Baskets | Gets the baskets of a customer. |
GET | /Customers/{Customer_id}/Orders | Returns a pageable list of all customer's orders. The default page size is 10. |
PUT | /Customers/{Customer_id}/Password | Updates the customer's password. |
POST | /Customers/{Customer_id}/Password_reset | Starts a password reset process. A password reset token is generated and passed together with the customer resolved by the id provided as path parameter to a afterPOST hook. The hook dw.ocapi.shop.customer.password_reset.afterPOST can utilize the provided reset token, for example to send a reset email. |
GET | /Customers/{Customer_id}/Payment_instruments | Gets customer payment instruments for an customer.
Can be limited to a specific payment
method by providing query parameter
payment_method_id . |
POST | /Customers/{Customer_id}/Payment_instruments | Adds a payment instrument to a customer information. |
GET | /Customers/{Customer_id}/Payment_instruments/{Payment_instrument_id} | Retrieves a customer's payment instrument by its id. |
DELETE | /Customers/{Customer_id}/Payment_instruments/{Payment_instrument_id} | Deletes a customer's payment instrument. |
Registers a customer. The mandatory data are the credentials and profile last name and email.
When using OAuth the password in the request must not be
set, otherwise an InvalidPasswordException
will be
thrown.
When using JWT the password is required.
Url
POST https://hostname:port/dw/shop/v16_2/customers
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
Response Document
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
CustomerAlreadyRegisteredException
|
Indicates that the resource is called with JWT token representing a registered customer. | |
400 |
MissingEmailException
|
Indicates that request document does not contain email. | |
400 |
MissingLastNameException
|
Indicates that request document does not contain last_name. | |
400 |
MissingLoginException
|
Indicates that request document does not contain login. | |
400 |
LoginAlreadyInUseException
|
Indicates that the given login is already used. | |
400 |
InvalidLoginException
|
Indicates that login doesn't match acceptance criteria. | |
400 |
InvalidPasswordException
|
Indicates that password doesn't match acceptance criteria. | |
400 |
MissingPasswordException
|
Indicates that password was not provided in JWT scenario. | |
400 |
InvalidEmailException
|
email (String) |
Indicates that the profile email address is not valid. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterPost
|
afterPost (customer : Customer , registration : CustomerRegistration ) : Status The function is called after a new customer registration.
|
dw.ocapi.shop.customer.beforePost
|
beforePost (registration : CustomerRegistration ) : Status The function is called before a new customer registration.
|
Sample
REQUEST:
POST /dw/shop/v16_2/customers
Host: example.com
Content-Type: application/json
{
"password":"12345!aBcD",
"customer": {
"login": "jsmith"
"email":"[email protected]",
"last_name":"Smith"
}
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer",
"auth_type" : "registered",
"creation_date" : "2015-09-09T15:50:53.142Z",
"customer_id" : "ada5ZiobJRE4Ma1fSaAogMDKgI",
"customer_no" : "00001140",
"email" : "[email protected]",
"last_name" : "Smith",
"login" : "jsmith"
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate
{
"_v" : "16.2",
"fault" :
{
"type" : "LoginAlreadyInUseException",
"message" : "Login is already in use."
}
}
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
:
About JWT
The token contains 3 sections:Authorization: Bearer
--token--
The client has to
include the token in the request header as
Authorization: Bearer --token--
in any follow up request. The server declines any
follow up requests without a token or which cannot be verified based on
the token signature or expiration time. A token nearing its expiration
time should be exchanged for a new one (type "refresh").
See "API Usage > JWT" for more details on using
JWT as an authentication mechanism. Url
POST https://hostname:port/dw/shop/v16_2/customers/auth
Formats
json, xml
Authentication
Name | Description |
---|---|
None | No authentication. |
Request Document
Response Document
Header Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
Authorization | String |
|
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
AuthorizationBasicMissingException
|
Indicates that no HTTP Authorization:Basic header was provided. | |
401 |
AuthenticationFailedException
|
credentialType (String) |
Indicates in case of type credentials the username is unknown or the password does not match. In case of type session the session is not active anymore or the dwsecuretoken value is invalid. In both cases the customer is disabled or locked. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.auth.afterAuth
|
afterAuth (authRequestType : EnumValue , customer : Customer ) : Status The function is called after the customer has been authenticated.
|
Sample
# Request type guest : obtain a token for a guest customer
REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Content-Type: application/json
{
"type" : "guest"
}
# Request type credentials : obtain a token for a registered customer
# Credentials are passed as HTTP Basic in base 64 in the form username:password
REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
"type" : "credentials"
}
# Request type session : obtain a token for a session
# session information passed as cookies
REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==;
dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==;
{
"type" : "session"
}
# Request type refresh : obtain a token in exchange for a token nearing expiration time
# Same mechanism used for guest and registered customer. Client ID needs to
# be provided and is checked against the id embedded in the token being refreshed.
REQUEST:
POST /dw/shop/v16_2/customers/auth?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Host: example.com
Content-Type: application/json
{
"type" : "refresh"
}
# in case of success, token returned in response header Authorization:Bearer
# "auth_type" is one of "guest" or "registered"
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer",
"auth_type" : "guest",
"customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
"preferred_locale" : "default"
}
# in case attempt to refresh an expired token:
RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "ExpiredTokenException",
"message" : "The provided token has expired."
}
}
# in case no Authorization Basic provided for type "credentials"
RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "AuthorizationBasicMissingException",
"message" : "Missing credentials: Add a Authorization:Basic header with base64 encoded username:password."
}
}
# in case missing or wrong username/password for type "credentials"
RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "AuthenticationFailedException",
"message" : "Failed to authenticate customer on base of Authorization:Basic header."
}
}
# in case of an outdated session for type "session"
RESPONSE:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "AuthenticationFailedException",
"message" : "Failed to authenticate customer on base of session."
}
}
Starts a password reset process. A password reset token is generated and together with the resolved customer is passed to a afterPOST hook. The customer resolution is based on the password reset request type. Currently the resolution can be done by email or login. In case of an email the password reset hook is only executed if one and only one customer has been identified for that email. In the case that more than one customers have been identified for the provided email the resource does nothing.
Url
POST https://hostname:port/dw/shop/v16_2/customers/password_reset
Formats
json, xml
Authentication
Name | Description |
---|---|
None | No authentication. |
Request Document
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customers.password_reset.afterPOST
|
afterPOST (customer : Customer , resetToken : String ) : Status Allows resetting a
customer password. See the example below sending an email with a
password reset link.
var variables: Map = new dw.util.HashMap(); variables.put("Customer", customer); variables.put("ResetPasswordToken", token); var template: Template = new dw.util.Template("mail/resetpasswordemail.isml"); var content: MimeEncodedText = template.render(variables); var mail: Mail = new Mail().setSubject("Password Reset").setContent(content).setFrom("[email protected]").addTo(customer.profile.email); mail.send();
|
Sample
#
# Example: Password reset
#
REQUEST:
POST /dw/shop/v16_2/customers/password_reset
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{"identification": "[email protected]", "type":"email"}
# in case of success:
RESPONSE:
HTTP/1.1 204 NO CONTENT
# in case of password reset failure in hook dw.ocapi.shop.customers.password_reset.afterPOST.
# The wrong status with code and message is returned by the custom code.
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"arguments" :
{
"extensionPoint" : "dw.ocapi.shop.customers.password_reset.afterPOST",
"statusCode" : "EXT_PW_CHANGE_FAIL",
"statusMessage" : "Password reset not successful in external system."
},
"type" : "HookStatusException",
"message" : "Error in ExtensionPoint 'dw.ocapi.shop.customers.password_reset.afterPOST'!"
}
}
Gets a customer.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}?expand={String}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | The customer id | mandatory=true, minLength=1, nullable=false |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
expand | String | The expand parameter. A comma separated list with the allowed values (addresses, paymentinstruments). |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
If customerId URL parameter does not match the verified customer represented by the JWT token (not relevant when using OAuth). | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
Sample
REQUEST:
GET /dw/shop/v16_2/customers/1234567890?expand=addresses,paymentinstruments HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json; charset=UTF-8
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
ETag: y4ad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd438kl
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v" : "16.2",
"_type" : "customer",
"adresses" :
[
{
"_type" : "customer_address",
"address1" : "10 Presidential Way",
"address_id" : "me",
"city" : "Woburn",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John M. Smith",
"last_name" : "Smith",
"postal_code" : "01801",
"salutation" : "Mr.",
"state_code" : "MA"
}
],
"auth_type" : "registered",
"creation_date" : "2015-08-20T11:30:36.000Z",
"customer_id" : "abfTWMDZOgi3JPzkHjv9IhmziI",
"customer_no" : "999",
"email" : "[email protected]",
"first_name" : "John",
"gender" : 1,
"last_name" : "Smith",
"payment_instruments" :
[
{
"_type" : "customer_payment_instrument",
"payment_bank_account" :
{
"_type" : "payment_bank_account"
},
"payment_card" :
{
"_type" : "payment_card",
"card_type" : "Visa",
"credit_card_expired" : false,
"expiration_month" : 2,
"expiration_year" : 2022,
"holder" : "John Smith",
"masked_number" : "***********ber2",
"number_last_digits" : "ber2"
},
"payment_instrument_id" : "beybQiWcyatEEaaadniwhKxxFl",
"payment_method_id" : "CREDIT_CARD",
"uuid" : "beybQiWcyatEEaaadniwhKxxFl",
}
],
"phone_business" : "234560003",
"phone_home" : "123450003",
"phone_mobile" : "345670003",
"c_origin" : "webshop"
}
# in case the authorized customer differs from the customer requested:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
"_v":"16.2",
"_type":"fault",
"fault":{
"type":"InvalidCustomerException",
"message":"Invalid customer."
}
}
Updates a customer.
Url
PATCH https://hostname:port/dw/shop/v16_2/customers/{customer_id}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the customer id | minLength=1 |
Header Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
If-Match | String |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
InvalidEmailException
|
email (String) |
Indicates that the provided email is not valid. |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterPatchCustomer
|
afterPatchCustomer (customer : Customer , customerInput : Customer ) : Status The function is called after a customer was updated.
|
dw.ocapi.shop.customer.beforePatchCustomer
|
beforePatchCustomer (customer : Customer , customerInput : Customer ) : Status The function is called before a customer is updated.
|
Sample
REQUEST:
PATCH /dw/shop/v16_2/customers/1234567890 HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type: application/json
{
email : "[email protected]",
fax : "+49 03641 78393 343",
c_origin :"webshop"
}
# in case of success
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type:application/json;charset=UTF-8
{
"auth_type" : "registered",
"creation_date" : "2015-08-20T11:30:36.000Z",
"customer_id" : "abfTWMDZOgi3JPzkHjv9IhmziI",
"customer_no" : "999",
"email" : "[email protected]",
"fax" : "+49 03641 78393 343",
"first_name" : "John",
"gender" : 1,
"last_name" : "Smith",
"phone_business" : "234560003",
"phone_home" : "123450003",
"phone_mobile" : "345670003",
"c_origin" : "webshop"
}
Returns a sorted pageable list of all customer addresses in the address book. The default page size is 10 customer addresses. The addresses are sorted so that the preferred address is always sorted first. The remaining addresses are sorted alphabetically by ID.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses?start={Integer}&count={Integer}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | The customer uuid | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
count | Integer | The maximum number of instances per request. Default value is 25. | maxIntegerValue=200, minIntegerValue=1 |
start | Integer | The result set index to return the first instance for. Default value is 0. | maxIntegerValue=999, minIntegerValue=0 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Sample
# Request, no paging details
REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8
# Request, with paging details
REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?start=0&count=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8
# in case of success
# note: "next" and / or "previous" links only exist when appropriate, and only if paging details were provided
RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_address_result",
"count" : 1,
"data" :
[
{
"_type" : "customer_address",
"address1" : "10 Free Way",
"address_id" : "private",
"city" : "Woburn",
"country_code" : "US",
"etag" : "0d715f5b688ff38c1f3394d56b84ddc40ca787b1adc6d62953713923b94f9cda",
"first_name" : "James",
"full_name" : "James Last",
"last_name" : "Last",
"postal_code" : "01801",
"salutation" : "Mr.",
"state_code" : "MA"
}
],
"next" : "https://.../s/.../dw/shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?count=1&start=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"start" : 0,
"total" : 2
}
Creates a new address with the given name for the given customer.
Url
POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer to create the address for | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
InvalidCustomerAddressIdException
|
addressId (String) |
Indicates that address name is not provided or it's blank. |
400 |
AddressIdAlreadyInUseException
|
Indicates that the provided address name is already used for the customer. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterPostAddress
|
afterPostAddress (customer : Customer , addressName : String ) : Status The function is called after adding an address to a customer.
|
dw.ocapi.shop.customer.beforePostAddress
|
beforePostAddress (customer : Customer , addressName : String ) : Status The function is called before adding an address to a customer.
|
Sample
REQUEST:
POST /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
{
"address_id": "home_address",
"address1" : "5 Wall St",
"address2" : "24 Presidential Way",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name": "John",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12a",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "Jim",
"state_code": "MA",
"title": "Dr."
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220
{
"_v" : "16.2",
"_type" : "customer_address",
"address1" : "5 Wall St",
"address2" : "24 Presidential Way",
"address_id" : "home_address",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Jim Murphy",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12a",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "Jim",
"state_code" : "MA",
"title" : "Dr."
}
# in case of validation failure - example response in case address_id is already used for this customer:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "AddressNameAlreadyInUseException",
"message" : "Customer address id is already in use."
}
}
Retrieves a customer's address by address name.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
address_name | String | the name of the address to retrieve | maxLength=256, minLength=1 |
customer_id | String | the id of the customer to retrieve the address for | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
404 |
CustomerAddressNotFoundException
|
addressId (String) customerNo (String) siteId (String) |
Indicates that the address with the given name in unknown for the customer with the given customer id. |
Sample
REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_address",
"address1" : "5 Wall St",
"address2" : "24 Presidential Way",
"address_id" : "59aed97608cf7f72",
"address_id" : "home_address",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John J. Murphy",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12a",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "J.",
"state_code" : "MA",
"title" : "Dr."
}
# in case of validation failure - example response in case of unknown address:
RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
"_v" : "16.2",
"fault" :
{
"type" : "NotFoundException",
"message" : "Customer address 'home_address' not found."
}
}
Deletes a customer's address by address name.
Url
DELETE https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
address_name | String | the name of the address to delete | maxLength=256, minLength=1 |
customer_id | String | the id of the customer to delete the address for | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
404 |
CustomerAddressNotFoundException
|
addressId (String) customerNo (String) siteId (String) |
Indicates that the address with the given name in unknown for the customer with the given customer id. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterDeleteAddress
|
afterDeleteAddress (customer : Customer , addressName : String ) : Status The function is called after removing an address of a customer.
|
dw.ocapi.shop.customer.beforeDeleteAddress
|
beforeDeleteAddress (customer : Customer , addressName : String ) : Status The function is called before removing an address of a customer.
|
Sample
REQUEST:
DELETE /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 204 NO CONTENT
# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "InvalidCustomerException",
"message" : "Invalid customer."
}
}
Updates a customer's address by address name.
Url
PATCH https://hostname:port/dw/shop/v16_2/customers/{customer_id}/addresses/{address_name}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
address_name | String | the name of the address to update | maxLength=256, minLength=1 |
customer_id | String | the id of the customer to update the address for | minLength=1 |
Header Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
If-Match | String | the ETag header value contained in the server response |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
AddressIdAlreadyInUseException
|
Indicates that the provided new address name is already used for the customer. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
404 |
CustomerAddressNotFoundException
|
addressId (String) customerNo (String) siteId (String) |
Indicates that the address with the given name in unknown for the customer with the given customer id. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterPatchAddress
|
afterPatchAddress (customer : Customer , addressName : String ) : Status The function is called after updating an address of a customer.
|
dw.ocapi.shop.customer.beforePatchAddress
|
beforePatchAddress (customer : Customer , addressName : String ) : Status The function is called before updating an address of a customer.
|
Sample
REQUEST:
PATCH /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json
{
"address_id" : "home_address",
"address1" : "6 Wall St",
"address2" : "26 Presidential Way",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name": "John",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12b",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "Jim",
"state_code": "MA",
"title": "Dr."
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220
{
"_v" : "16.2",
"_type" : "customer_address",
"address1" : "6 Wall St",
"address2" : "26 Presidential Way",
"address_id" : "home_address",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Jim Murphy",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12b",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "Jim",
"state_code" : "MA",
"title" : "Dr."
}
# in case of validation failure - example response in case of attempt to update non-existing address:
RESPONSE:
HTTP/1.1 404 NOT FOUND
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "NotFoundException",
"message" : "Customer address 'home_address' not found."
}
}
REQUEST:
PATCH /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/home_address
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match:634da3c275e55a6d66099aaa3d1550fa82ec43d5131bd5b64dde75c4ca942e9c
Content-Type: application/json
{
"address_id" : "old_home_address",
}
# in case of success:
RESPONSE:
HTTP/1.1 301 MOVED PERMANENTLY
Location: /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/addresses/old_home_address
Content-Type: application/json;charset=UTF-8
Etag: ede395db479773613c6538aad756a4ef990b2f80003865964c88a6854f09c220
{
"_v" : "16.2",
"_type" : "customer_address",
"address1" : "6 Wall St",
"address2" : "26 Presidential Way",
"address_id" : "old_home_address",
"city" : "Burlington",
"company_name" : "Salesforce",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Jim Murphy",
"job_title" : "Developer",
"last_name" : "Murphy",
"phone" : "408-555-1212",
"postal_code" : "01805",
"post_box" : "12b",
"preferred" : false,
"salutation" : "Mr.",
"second_name" : "Jim",
"state_code" : "MA",
"title" : "Dr."
}
Gets the baskets of a customer.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/baskets
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer to retrieve the baskets for | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
if customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Sample
# Request
REQUEST:
GET /dw//shop/v16_2/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/baskets?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8
# in case of success
RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "baskets_result",
"baskets" :
[
{
"_type" : "basket",
"basket_id" : "bccO1aOjgEnuIaaadk7pYO2rFE",
...
},
{
"_type" : "basket",
"basket_id" : "bcs5vaOjgEQ9Uaaadk9zQIrXE6",
...
}
],
"total" : 2
}
Returns a pageable list of all customer's orders. The default page size is 10.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/orders?start={Integer}&count={Integer}&cross-sites={Boolean}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the customer uuid | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
count | Integer | the maximum number of instances per request; default value is 10 | maxIntegerValue=200, minIntegerValue=1 |
cross-sites | Boolean | the flag whether all sites should be searched; ignored in
case of JWT; default value is false
|
|
start | Integer | the result set index to return the first instance for; default value is 0 | minIntegerValue=0 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Sample
# Request, no paging details
REQUEST:
GET /dw/shop/v16_2/customers/cevGs1bS2Xac8fpwe6GHJEzYlg/orders?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json
# Request, with paging details
REQUEST:
GET /dw/shop/v16_2/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?start=0&count=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json
# in case of success
# note: "next" and / or "previous" links only exist when appropriate, and only if paging details were provided
RESPONSE:
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_order_result",
"count" : 1,
"data" :
[
{
"_type" : "order",
"adjusted_merchandize_total_tax" : 5.00,
"adjusted_shipping_total_tax" : 0.00,
...
"customer_info" :
{
"_type" : "customer_info",
"customer_id" : "bczhcasxVFpLdxtF05OIPEb25u",
"customer_name" : "John Smith",
"email" : "[email protected]"
},
...
"order_no" : "00001228",
...
"payment_instruments" :
[
...
],
"product_items" :
[
...
],
"product_sub_total" : 16.29,
"product_total" : 16.29,
"shipments" :
[
...
],
"shipping_items" :
[
...
],
"shipping_total" : 0.01,
"shipping_total_tax" : 0.00,
"status" : "created",
"taxation" : "net",
"tax_total" : 5.00,
...
}
],
"next" : "https://.../.../.../dw/shop/v16_2/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?count=1&start=1&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"start" : 0,
"total" : 3
}
# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "InvalidCustomerException",
"message" : "Invalid customer."
}
}
Updates the customer's password.
Url
PUT https://hostname:port/dw/shop/v16_2/customers/{customer_id}/password
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
Request Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the customer id | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
If customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.putPassword
|
putPassword (customer : Customer , passwordChangeRequest : PasswordChangeRequest ) : Status The function is called to update a customer's password. Use custom implementation to change password e.g. in third party systems. The default implementation will try to change the authenticated user password with the new password provided in the request. In case of an error the default implementation will return the error statuses listed in {@link dw.customer.Credentials#setPassword(String, String, boolean)}.
|
Sample
REQUEST:
PUT /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/password
Host: example.com
Authorization: Bearer eyJfdiI6IjEiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXUy.....
Content-Type: application/json
{"current_password": "01dpass", "password": "newpass"}
# in case of success:
RESPONSE:
HTTP/1.1 204 NO CONTENT
#example response in case of an empty new password:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"arguments" :
{
"extensionPoint" : "dw.ocapi.shop.customer.putPassword",
"statusCode" : "The new password is empty.",
"statusMessage" : "The new password is empty."
},
"type" : "HookStatusException",
"message" : "Error in ExtensionPoint 'dw.ocapi.shop.customer.putPassword'!"
}
}
Starts a password reset process. A password reset token is generated and passed together with the customer resolved by the id provided as path parameter to a afterPOST hook. The hook dw.ocapi.shop.customer.password_reset.afterPOST can utilize the provided reset token, for example to send a reset email.
Url
POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/password_reset
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer specified was not found. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.password_reset.afterPOST
|
afterPOST (customer : Customer , resetToken : String ) : Status Allows resetting a
customer password. See the example below sending an email with a
password reset link.
var variables: Map = new dw.util.HashMap(); variables.put("Customer", customer); variables.put("ResetPasswordToken", token); var template: Template = new dw.util.Template("mail/resetpasswordemail.isml"); var content: MimeEncodedText = template.render(variables); var mail: Mail = new Mail().setSubject("Password Reset").setContent(content).setFrom("[email protected]").addTo(customer.profile.email); mail.send();
|
Sample
REQUEST:
PUT /dw/shop/v16_2/customers/cdRXAiWbPdMhcaaadh5hZczLu5/password_reset
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
# in case of success:
RESPONSE:
HTTP/1.1 204 NO CONTENT
# in case of password reset failure in hook dw.ocapi.shop.customer.password_reset.afterPOST.
# The wrong status with code and message is returned by the custom code.
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"arguments" :
{
"extensionPoint" : "dw.ocapi.shop.customer.password_reset.afterPOST",
"statusCode" : "EXT_PW_CHANGE_FAIL",
"statusMessage" : "Password reset not successful in external system."
},
"type" : "HookStatusException",
"message" : "Error in ExtensionPoint 'dw.ocapi.shop.customer.password_reset.afterPOST'!"
}
}
payment_method_id
. Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments?payment_method_id={String}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
CustomerPaymentInstrumentResult
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer to retrieve the payment instruments for | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
payment_method_id | String | the id of the payment method, if null - all payment instruments are retrieved |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Sample
REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_payment_instrument_result",
"count" : 2,
"data" :
[
{
"_type" : "customer_payment_instrument",
"payment_bank_account" :
{
"_type" : "payment_bank_account"
},
"payment_card" :
{
"_type" : "payment_card",
"card_type" : "Visa",
"credit_card_expired" : false,
"expiration_month" : 2,
"expiration_year" : 2022,
"holder" : "John Doe",
"masked_number" : "***********1111",
"number_last_digits" : "1111"
},
"payment_method_id" : "CREDIT_CARD",
"payment_instrument_id" : "cdlPgiWbN6LM2aaadkcia6MgbA",
"c_strValue" : "custom value 2"
},
{
"_type" : "customer_payment_instrument",
"bank_routing_number" : "bankrouting3446",
"gift_certificate_code_masked" : "*****code",
"payment_bank_account" :
{
"_type" : "payment_bank_account",
"drivers_license_last_digits" : "e111",
"drivers_license_state_code" : "MA",
"holder" : "Joe Doe",
"masked_drivers_license" : "**********e111",
"masked_number" : "**********t111",
"number_last_digits" : "t111"
},
"payment_card" :
{
"_type" : "payment_card",
"credit_card_expired" : false
},
"payment_method_id" : "OCAPI_Payment_Simple",
"payment_instrument_id" : "cdTsgiWbN6DFEaaadkbia6MgbA",
"c_strValue" : "custom value 1"
}
],
"total" : 2
}
# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "InvalidCustomerException",
"message" : "Invalid customer."
}
}
Adds a payment instrument to a customer information.
Url
POST https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
CustomerPaymentInstrumentRequest
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown. |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterPostPaymentInstrument
|
afterPostPaymentInstrument (customer : Customer , paymentInstrument : CustomerPaymentInstrumentRequest ) : Status The function is called after a payment instrument was added to a customer.
|
dw.ocapi.shop.customer.beforePostPaymentInstrument
|
beforePostPaymentInstrument (customer : Customer , paymentInstrument : CustomerPaymentInstrumentRequest ) : Status The function is called before a payment instrument is added to a customer.
|
Sample
REQUEST:
POST /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json; charset=UTF-8
{
"payment_card":{
"expiration_year":2027,
"expiration_month":7,
"valid_from_month":8,
"valid_from_year":2007,
"issue_number":"i117",
"number":"1234567",
"holder":"Joe Doe",
"card_type":"MasterCard"
},
"gift_certificate_code": "gift_code7",
"payment_method_id": "OCAPI_Payment_Simple",
"bank_routing_number":"bankrouting3776",
"c_strValue":"custom value 7"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_payment_instrument",
"bank_routing_number" : "bankrouting3776",
"gift_certificate_code_masked" : "******ode7",
"payment_bank_account" :
{
"_type" : "payment_bank_account"
},
"payment_card" :
{
"_type" : "payment_card",
"card_type" : "MasterCard",
"credit_card_expired" : false,
"expiration_month" : 7,
"expiration_year" : 2027,
"holder" : "Joe Doe",
"issue_number" : "i117",
"masked_number" : "***4567",
"number_last_digits" : "4567",
"valid_from_month" : 8,
"valid_from_year" : 2007
},
"payment_method_id" : "OCAPI_Payment_Simple",
"payment_instrument_id" : "cdOLciWbOsYl6aaadkwcsx9xHH",
"c_strValue" : "custom value 7"
}
# in case of validation failure - example response when the customer is not found:
RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "NotFoundException",
"message" : "No customer with id 'acE9xUWs5ea75qwTh0Svi2XfRY' found."
}
}
Retrieves a customer's payment instrument by its id.
Url
GET https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments/{payment_instrument_id}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer to retrieve the payment instrument for | minLength=1 |
payment_instrument_id | String | the id of the payment instrument to be retrieved | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
404 |
PaymentInstrumentNotFoundException
|
paymentInstrumentId (String) |
Indicates that the payment instrument with the given id is unknown for the customer with the given customer id. |
Sample
REQUEST:
GET /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/eg5hEiWbPdcaQaaaekty3fqx1o
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"_type" : "customer_payment_instrument",
"payment_bank_account" :
{
"_type" : "payment_bank_account"
},
"payment_card" :
{
"_type" : "payment_card",
"card_type" : "Visa",
"credit_card_expired" : false,
"expiration_month" : 3,
"expiration_year" : 2023,
"holder" : "John Doe",
"masked_number" : "***********1111",
"number_last_digits" : "1111"
},
"payment_method_id" : "CREDIT_CARD",
"payment_instrument_id" : "eg5hEiWbPdcaQaaaekty3fqx1o",
"c_strValue" : "custom Test value 3"
}
# in case of validation failure - example response in case of unknown customer payment intrument:
RESPONSE:
HTTP/1.1 404 NOT FOUND
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
"_v" : "16.2",
"fault" :
{
"type" : "NotFoundException",
"message" : "The payment instrument with uuid 'cdmh6iWbObcXUaaadkPA7ydxnr' was not found."
}
}
Deletes a customer's payment instrument.
Url
DELETE https://hostname:port/dw/shop/v16_2/customers/{customer_id}/payment_instruments/{payment_instrument_id}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_id | String | the id of the customer to delete the payment instrument for | minLength=1 |
payment_instrument_id | String | the id of the payment instrument to be deleted | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
CustomerNotFoundException
|
customerId (String) |
Indicates that the customer with the given customer id is unknown for the site. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.customer.afterDeletePaymentInstrument
|
afterDeletePaymentInstrument (customer : Customer , paymentInstrumentId : String ) : Status The function is called after removing a payment instrument of a customer.
|
dw.ocapi.shop.customer.beforeDeletePaymentInstrument
|
beforeDeletePaymentInstrument (customer : Customer , paymentInstrumentId : String ) : Status The function is called before removing a payment instrument of a customer.
|
Sample
REQUEST:
DELETE /s/SiteGenesis/dw/shop/v16_2/customers/acE9xUWs5ea75qwTh0Svi2XfRY/payment_instruments/cdmh6iWbObcXUaaadkPA7ydxnr
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 204 NO CONTENT
# in case of validation failure - example response in case of registered customer scenario when the customer id does not match the authenticated customer id:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
"_v" : "16.2",
"fault" :
{
"type" : "InvalidCustomerException",
"message" : "Invalid customer."
}
}