Http Method | Resource | Description |
---|---|---|
POST | /Baskets | Creates a new basket. The created basket is initialized
with default values. Data provided in the body document will be
populated into the created basket. It can be updated with
further shop api calls.
Considered values from the request body are:
basketId property, which should be integrated
into the path of an update request, for example a POST to
/baskets/{basketId}/items .
The resource supports JWT or OAuth
tokens for authentication:
/baskets/{basketId}/submit or deleted
using a DELETE to resource /baskets/{basketId} .
The number of open baskets allowed depends on the
authentication method used:
|
GET | /Baskets/{Basket_id} | Gets a basket. |
PATCH | /Baskets/{Basket_id} | Updates a basket. Only the currency of the basket and the custom properties of the basket and of the shipping items will be considered. |
DELETE | /Baskets/{Basket_id} | Removes a basket. |
PUT | /Baskets/{Basket_id}/Billing_address | Sets the billing address of a basket. |
POST | /Baskets/{Basket_id}/Coupons | Adds a coupon to an existing basket. |
DELETE | /Baskets/{Basket_id}/Coupons/{Coupon_item_id} | Removes a coupon from the basket. |
PUT | /Baskets/{Basket_id}/Customer | Sets customer information for an existing basket. |
POST | /Baskets/{Basket_id}/Gift_certificate_items | Adds a gift certificate item to an existing basket. |
POST | /Baskets/{Basket_id}/Items | Adds a new item to a basket.
The added item is associated with the
specified shipment. If no shipment id is specified, the added
item is associated with the default shipment.
Considered values from the request body
are:
|
PATCH | /Baskets/{Basket_id}/Items/{Item_id} | Updates an item in a basket.
The following values in the request body
are considered by the server:
|
DELETE | /Baskets/{Basket_id}/Items/{Item_id} | Removes a product item from the basket. |
POST | /Baskets/{Basket_id}/Notes | Adds a note to an existing basket. |
GET | /Baskets/{Basket_id}/Notes | Retrieves notes for a basket. |
POST | /Baskets/{Basket_id}/Payment_instruments | Adds a payment instrument to a basket. |
PATCH | /Baskets/{Basket_id}/Payment_instruments/{Payment_instrument_id} | Updates a payment instrument of a basket. |
DELETE | /Baskets/{Basket_id}/Payment_instruments/{Payment_instrument_id} | Removes a payment instrument of a basket. |
GET | /Baskets/{Basket_id}/Payment_methods | Gets applicable payment methods for an existing basket. |
POST | /Baskets/{Basket_id}/Price_adjustments | Adds a custom manual price adjustment to the basket. |
DELETE | /Baskets/{Basket_id}/Price_adjustments/{Price_adjustment_id} | Removes a custom manual price adjustment from the basket. |
POST | /Baskets/{Basket_id}/Shipments | Creates a new shipment for a basket.
The created shipment is initialized with
values provided in the body document and can be updated with
further data API calls. Considered from the body are the
following properties if specified:
|
PATCH | /Baskets/{Basket_id}/Shipments/{Shipment_id} | Updates a shipment for a basket.
The shipment is initialized with values
provided in the body document and can be updated with further
data API calls. Considered from the body are the following
properties if specified
|
PUT | /Baskets/{Basket_id}/Shipments/{Shipment_id}/Shipping_address | Sets a shipping address of a specific shipment of a basket. |
PUT | /Baskets/{Basket_id}/Shipments/{Shipment_id}/Shipping_method | Sets a shipping method to a specific shipment of a basket. |
GET | /Baskets/{Basket_id}/Shipments/{Shipment_id}/Shipping_methods | Gets the applicable shipping methods for a certain shipment of a basket. |
POST | /Baskets/{Basket_id}/Submit | Submits an order based on a prepared basket. Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. |
basketId
property, which
should be integrated into the path of an update request, for example a
POST to /baskets/{basketId}/items
.
The resource supports JWT or OAuth tokens for
authentication: /baskets/{basketId}/submit
or
deleted using a DELETE to resource
/baskets/{basketId}
. The number of open baskets
allowed depends on the authentication method used: Url
POST https://hostname:port/dw/shop/v15_9/baskets
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 |
InvalidPaymentMethodIdException
|
paymentMethodId (String) |
Indicates that the provided payment method is invalid or not applicable. |
400 |
InvalidCustomerException
|
Thrown if the customerId URL parameter does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
CustomerBasketsQuotaExceededException
|
basketIds (String) |
Thrown if a new basket cannot be created because the max number of baskets per customer quota will be exceeded. |
400 |
DuplicateShipmentIdException
|
shipmentId (String) |
Indicates that the same shipment id appeared twice in the body. |
400 |
MissingCouponCodeException
|
Thrown if the coupon number is not provided. | |
400 |
InvalidPriceAdjustmentLevelException
|
Indicates that a fixed price adjustment was added at order level which is disallowed. | |
400 |
InvalidPromotionIdException
|
promotionId (String) |
When attempting to add a price adjustment, indicates that a promotion id was used twice. |
400 |
SystemPromotionIdException
|
promotionId (String) |
When attempting to add a price adjustment, indicates that a system promotion id was used as a manual promotion id. |
400 |
TooManyPromotionsException
|
Indicates that more than one hundred price adjustments would have been created. | |
404 |
NotFoundException
|
Thrown if the shipment with the given shipment id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPost
|
afterPost (basket : Basket ) : Status The function is called after the basket was created.
|
Sample
# create a basket with the given token
REQUEST:
POST /dw/shop/v15_9/baskets?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json
# in case of success, response contains new created basket with its id and ETag in response header
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
"_flash" :
[
...
]
...
"basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
"currency" : "USD",
"customer_info" :
{
"_type" : "customer_info",
"customer_id" : "adNJrbxJovaT5DPxUSfOywk6Et",
"email" : ""
},
...
"order_total" : 0.00,
"product_sub_total" : 0.00,
"product_total" : 0.00,
"shipments" :
[
{
"_type" : "shipment",
"id" : "me",
"shipment_id" : "bc5OTaOjgEqUoaaadkvHwbgrP5"
}
],
"shipping_items" :
[
{
...
"shipment_id" : "me",
"item_id" : "bcwsbaOjgEqUsaaadkvHwbgrP5"
}
],
"shipping_total" : 0.00,
"shipping_total_tax" : 0.00,
"taxation" : "net",
"tax_total" : 0.00
}
Gets a basket.
Url
GET https://hostname:port/dw/shop/v15_9/baskets/{basket_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 |
---|---|---|---|
basket_id | String | the id of the basket to be retrieved | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Sample
# get a basket by id, request includes Authorization:Bearer token and If-Match with ETag
REQUEST:
GET /dw/shop/v15_9/baskets/bczFTaOjgEqUkaaadkvHwbgrP5?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type: application/json
# in case of success
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
"currency" : "USD",
...
}
# in case basket for given id not found
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "No basket with id 'xxbcql1aOjgEsaaadkOtMbgrQq' found."
}
}
Updates a basket. Only the currency of the basket and the custom properties of the basket and of the shipping items will be considered.
Url
PATCH https://hostname:port/dw/shop/v15_9/baskets/{basket_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | 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
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
InvalidShippingItemIdException
|
shippingItemId (String) |
Indicates that the given shipping item id is null or empty. |
400 |
DuplicateShippingItemIdException
|
shippingItemId (String) |
Indicates that a few shipping items with the same item id are provided. |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or the shipping item with the given item id is unknown for the basket. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPatch
|
afterPatch (basket : Basket , basketInput : Basket ) : Status The function is called after updating of the basket.
|
dw.ocapi.shop.basket.beforePatch
|
beforePatch (basket : Basket , basketInput : Basket ) : Status The function is called before updating of the basket.
|
Sample
REQUEST:
PATCH /dw/shop/v15_9/baskets/bczFTaOjgEqUkaaadkvHwbgrP5
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type: application/json
{
"c_newCustomProperty:"customValue"
}
# in case of success
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
"c_newCustomProperty" : "customValue",
...
}
# in case basket for given id not found
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "No basket with id 'xxbcql1aOjgEsaaadkOtMbgrQq' found."
}
}
Removes a basket.
Url
DELETE https://hostname:port/dw/shop/v15_9/baskets/{basket_id}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
basket_id | String | the id of the basket to be retrieved | minLength=1 |
Header Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
If-Match | String | E-Tag to match to basket. |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterDelete
|
afterDelete (basketId : String ) : Status The function is called after removing a basket.
|
dw.ocapi.shop.basket.beforeDelete
|
beforeDelete (basket : Basket ) : Status The function is called before removing a basket.
|
Sample
# remove a basket by id, request includes Authorization:Bearer token
REQUEST:
DELETE /dw/shop/v15_9/baskets/bczFTaOjgEqUkaaadkvHwbgrP5?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json
# in case of success
RESPONSE:
HTTP/1.1 204 NO CONTENT
# in case of outdated IfMatch header
RESPONSE:
HTTP/1.1 412 PRECONDITION FAILED
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "PreconditionFailedException",
"message" : "The If-Match base point 'etag123...' is outdated. The resource has been modified."
}
}
Sets the billing address of a basket.
Url
PUT https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/billing_address?use_as_shipping={Boolean}&customer_address_id={String}
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 |
---|---|---|---|
basket_id | String | The id of the basket to be modified. | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_address_id | String | The id of the customer address to be set as billing address. Cannot be used together with an existing body. | minLength=1 |
use_as_shipping | Boolean | The flag indicating whether the given address will also be used as shipping address for the default shipment. |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
CustomerAddressIdNotApplicableException
|
Indicates that both customer_address_id and address body was provided. | |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token (not relevant when using OAuth). | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or that the address specified by customer_address_id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPutBillingAddress
|
afterPutBillingAddress (basket : Basket , billingAddress : OrderAddress ) : Status The function is called after setting of the billing address to the basket.
|
dw.ocapi.shop.basket.beforePutBillingAddress
|
beforePutBillingAddress (basket : Basket , billingAddress : OrderAddress ) : Status The function is called before setting of the billing address to the basket.
|
Sample
REQUEST:
PUT /dw/shop/v15_9/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"first_name":"John",
"last_name":"Smith",
"city":"Boston",
"country_code":"US",
"c_strValue":"cTest"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"billing_address" :
{
"_type" : "order_address",
"city" : "Boston",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Smith",
"last_name" : "Smith",
"c_strValue" : "cTest"
},
...
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 409 CONFLICT
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" : {
"type" : "IfMatchRequiredException",
"message" : "If-Match header is required, but no one was provided. Please provide an If-Match header."
}
}
# with an address from a customer profile
REQUEST:
PUT /dw/shop/v15_9/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address?customer_address_id=home
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"billing_address" :
{
"_type" : "order_address",
"city" : "Boston",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Smith",
"last_name" : "Smith",
"c_strValue" : "cTest"
},
...
}
Adds a coupon to an existing basket.
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/coupons
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 |
---|---|---|---|
basket_id | String | The id of the basket to be modified. | 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 customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
MissingCouponCodeException
|
Thrown if the coupon number is not provided. | |
400 |
InvalidCouponItemException
|
couponCode (String) |
Thrown if the coupon number specified is invalid. |
400 |
InvalidCouponStatusException
|
basketNo (String) siteId (String) couponCode (String) couponStatus (String) |
Thrown if the coupon status does not allow the coupon to be added to the basket. |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostCoupon
|
afterPostCoupon (ctor : Basket , couponItem : CouponItem ) : Status The function is called after adding a coupon to a basket.
|
dw.ocapi.shop.basket.beforePostCoupon
|
beforePostCoupon (ctor : Basket , couponItem : CouponItem ) : Status The function is called before adding a coupon to a basket.
|
Sample
REQUEST:
POST /dw/shop/v15_9/baskets/bcRTDaOjgyscwaaadkrhhQHmrP/coupons
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"code" : "the99coupon"
}
# 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" : "15.9",
...
"basket_id" : "bcRTDaOjgyscwaaadkrhhQHmrP",
"coupon_items" :
[
{
"_type" : "coupon_item",
"code" : "the99coupon",
"status_code" : "applied",
"valid" : true
}
],
...
}
# 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" : "15.9",
"fault" :
{
"type" : "InvalidCouponItemException",
"message" : "Invalid coupon code 'notExitingCoupon'"
}
}
Removes a coupon from the basket.
Url
DELETE https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/coupons/{coupon_item_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
coupon_item_id | String | the id of the coupon item to be removed | 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 customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or that the couponItemId URL parameter does not match any coupon item id in the basket. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.data.basket.afterRemoveCoupon
|
afterRemoveCoupon (basket : Basket , couponCode : String ) : Status The function is called after a coupon is removed from the basket.
|
dw.ocapi.data.basket.beforeRemoveCoupon
|
beforeRemoveCoupon (basket : Basket , couponCode : String ) : Status The function is called before a coupon is removed from the basket.
|
Sample
REQUEST:
DELETE /shop/v15_9/baskets/cgHV79aadbwZIaaaekLlYxEcg7/coupons/cd5ON9aacbJAQaaadlc1RUojQv HTTP/1.1
Host: example.com
Authorization:Bearer 2afa983a-3ece-441d-a6f4-cdb4af1cff56 If-Match:04215c927573e7cfe8d0def82571e7cccd47fb06c64a3f2c58e2e7e1d0de06ed Content-Type:application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
Date:Thu, 19 Mar 2015 13:34:17 GMT
Server:Commerce Cloud Digital Server/2.4.10 (Unix) OpenSSL/1.0.1f
Content-Length:2011
ETag:34dc82a9556bb8d1c1ae0207244190666734f162a186a9ec854f696380f6a87b
Keep-Alive:timeout=15, max=98
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
}
# in case of error:
RESPONSE:
HTTP/1.1 404 Not Found
Date:Thu, 19 Mar 2015 13:34:17 GMT
Content-Length:114
Keep-Alive:timeout=15, max=96
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "Coupon item id 'cd5ON9aacbJAQaaadlc1RUojQv' could not be found."
}
}
Sets customer information for an existing basket.
Url
PUT https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/customer
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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | 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 customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
400 |
CustomerBasketsQuotaExceededException
|
basketIds (String) |
Indicates that the customer cannot be set to the basket because the max number of baskets per customer quota will be exceeded. |
404 |
NotFoundException
|
Indicates that the customer with the given customer number is unknown or the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPutCustomer
|
afterPutCustomer (basket : Basket , customerInfo : CustomerInfo ) : Status The function is called after setting of customer information for the basket.
|
dw.ocapi.shop.basket.beforePutCustomer
|
beforePutCustomer (basket : Basket , customerInfo : CustomerInfo ) : Status The function is called before setting of customer information for the basket.
|
Sample
REQUEST:
PUT /dw/shop/v15_9/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/customer
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"customer_no":"customer0012",
"email":"[email protected]"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"customer_info" :
{
"_type" : "customer_info",
"customer_id" : "bc4ZGjva2LWAZVEvE6MvlbX6GD",
"customer_no" : "customer0012",
"email" : "[email protected]"
},
...
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 409 CONFLICT
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "No customer with number 'customer0013' for site 'SiteGenesis' found."
}
}
Adds a gift certificate item to an existing basket.
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/gift_certificate_items
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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | 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 |
---|---|---|---|
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or that the shipment with the given shipment id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostGiftCertificateItem
|
afterPostGiftCertificateItem (basket : Basket , item : GiftCertificateItem ) : Status The function is called after adding a gift certificate item to a basket.
|
dw.ocapi.shop.basket.beforePostGiftCertificateItem
|
beforePostGiftCertificateItem (basket : Basket , item : GiftCertificateItem ) : Status The function is called before adding a gift certificate item to a basket.
|
Sample
#
# Example: Add a gift certificate item to a basket
#
REQUEST:
POST /dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/gift_certificate_items
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"recipient_email" : "[email protected]",
"recipient_name" : "Mathias Doe",
"sender_name" : "John Doe",
"message" : "Present from your brother",
"amount" : 200.00
}
# 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
ETag: eaed36b37b7ba3f9f4550d9f76754fe58f2274244cc0b387e6820cae69c9c86e
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
"_v" : "15.9",
"_type" : "basket",
...
"gift_certificate_line_items" :
[
{
"_type" : "gift_certificate_item",
"amount" : 200.00,
"message" : "Present from your brother",
"recipient_email" : "[email protected]",
"recipient_name" : "Jane Doe",
"sender_name" : "John Doe",
"shipment_id" : "beRyAiWcyEk4UaaadmbdFBKNcy"
}
],
...
}
option_items
property. These
option items must contain option_id
and
option_value_id
. Also, the values you specify must be
valid for the option product that this product item represents.
Otherwise, the server throws an
InvalidProductOptionItemException
or an
InvalidProductOptionValueItemException
.Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/items
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 |
---|---|---|---|
basket_id | String | The id of the basket to be modified. | 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 |
InvalidProductIdException
|
Indicates that the given product id is
null or invalid. |
|
400 |
InvalidProductItemException
|
productId (String) |
Indicates that the product with the given product id is
unknown, offline or not assigned to site catalog or the given
product item quantity is null or
invalid. |
400 |
ProductItemNotAvailableException
|
productId (String) quantity (Decimal) |
Indicates that the requested product quantity is not available. |
400 |
InvalidProductTypeException
|
type (String) |
Indicates that the product cannot be added to the basket because of its type. |
400 |
InvalidOptionItemException
|
Indicates that an option with the given option id or option value id is not supported. | |
400 |
BasketQuotaExceededException
|
Indicates that the maximum allowed number, of products added to the basket, has been exceeded. | |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or the basket does not contain shipment with the given shipment id. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostItem
|
afterPostItem (basket : Basket , item : ProductItem ) : Status The function is called after adding of the item to a shipment of the basket.
|
dw.ocapi.shop.basket.beforePostItem
|
beforePostItem (basket : Basket , item : ProductItem ) : Status The function is called before adding of the item to a shipment of the basket.
|
Sample
REQUEST:
POST /dw/shop/v15_9/baskets/this/items
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"product_id" : "cup-white",
"quantity" : 1.00,
"c_anycustomproperty": "CustomPropertyValue"
}
# 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" : "15.9",
...
"product_items" : [
{
"adjusted_tax" : 5.00,
"base_price" : 15.99,
"bonus_product_line_item" : false,
"item_text" : "cup-white Product details...",
"price" : 15.99,
"price_after_item_discount" : 15.99,
"price_after_order_discount" : 15.99,
"product_id" : "cup-white",
"product_name" : "cup-white Product Name",
"quantity" : 1.0,
"shipment_id" : "me",
"tax" : 5.00,
"tax_basis" : 15.99,
"tax_class_id" : null,
"tax_rate" : 0.05,
"item_id" : "dedcaiWbNShRkaaadhKSo2jbZi",
"c_anycustomproperty": "CustomPropertyValue"
}
],
...
}
# 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" : "15.9",
"fault" :
{
"type" : "InvalidProductItemException",
"message" : "Product 'cup-white' is unknown, offline or not assigned to site catalog."
}
}
product_id
: a valid product id. The purpose of
this value is to exchange a variation of a variation product.shipment_id
: a valid shipment id. The purpose of
this value is to move a product item to another shipment.quantity
: a number between 0 and 999. The purpose
of this value is to change quantity of the product item. If quantity
is 0, the product item is removed.option_items/option_value_id
: a valid option
value id. The purpose of this value is to exchange an option value for
an option item of an option product.
This is only possible if the product item is an option product. To
change option values a collection of option items to be changed need
to be provided in property option_items
. Those
option_items
need to contain
option_id
and option_value_id
. The
provided values must be valid for the option product that this product
item represents. Otherwise
InvalidProductOptionItemException
or
InvalidProductOptionValueItemException
will be
thrown.
custom properties c_<CUSTOM_NAME>
: a
value corresponding to the type defined for custom attribute
<CUSTOM_NAME> of ProductLineItem. The purpose of this value is
to add or change the value of a custom attribute defined for
ProductLineItem.Url
PATCH https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/items/{item_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
item_id | String | the it of the item to be updated | 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 |
InvalidProductItemIdException
|
productItemId (String) |
Indicates that the product item with given id was not found for the basket. |
400 |
InvalidProductItemException
|
productId (String) |
Indicates that the given product id in the request body is invalid. |
400 |
InvalidOptionItemException
|
Indicates that an option with the specified option id or option value id is not supported. | |
400 |
InvalidShipmentIdException
|
shipmentId (String) |
Indicates that the given shipment id is invalid. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id or a shipment with the given id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPatchItem
|
afterPatchItem (basket : Basket , item : ProductItem ) : Status The function is called after updating of the basket's item.
|
dw.ocapi.shop.basket.beforePatchItem
|
beforePatchItem (basket : Basket , item : ProductItem ) : Status The function is called before updating of the basket's item.
|
Sample
#
# Example: Update option value
#
REQUEST:
PATCH /dw/shop/v15_9/baskets/cd6HwiWbLaZuUaaadgtglhMTrG/items/cdheYiWbLasNkaaadgwMthMTrG HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
If-Match: t9ccde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73b8h6
{
"product_id": "IPad2",
"quantity": 1,
"option_items": [
{
"option_id": "Warranty",
"option_value_id": "oneYear"
}
]
}
# 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" : "15.9",
...
"product_items" : [
{
"adjusted_price" : 20.00,
"adjusted_tax" : 1.00,
"base_price" : 20.00,
"bonus_product_line_item" : false,
"item_text" : "IPad 2",
"option_items" : [
{
"adjusted_tax" : 1.00,
"base_price" : 20.00,
"item_text" : "Warranty One Year",
"option_id" : "Warranty",
"option_value_id" : "oneYear",
"price" : 20.00,
"quantity" : 1.0,
"tax" : 1.00,
"tax_basis" : 20.00,
"tax_class_id" : "DefaultTaxClass",
"tax_rate" : 0.05
}
],
"price" : 20.00,
"product_id" : "IPad2",
"product_name" : "IPad 2",
"quantity" : 1.0,
"shipment_id" : "me",
"tax" : 1.00,
"tax_basis" : 20.00,
"tax_class_id" : "DefaultTaxClass",
"tax_rate" : 0.05,
"item_id" : "cdheYiWbLasNkaaadgwMthMTrG"
}
],
"product_sub_total" : 40.00,
"product_total" : 40.00,
...
}
#
# Example Response: Update option value, invalid option id
#
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 47
{
"_v" : "15.9",
"fault" :
{
"type" : "InvalidOptionItemException",
"message" : "Product option 'Insurance' is not supported."
}
}
Removes a product item from the basket.
Url
DELETE https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/items/{item_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
item_id | String | the id of the product item to be removed | 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 customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterDeleteItem
|
afterDeleteItem (basket : Basket , productItemId : String ) : Status The function is called after a basket item is removed.
|
dw.ocapi.shop.basket.beforeDeleteItem
|
beforeDeleteItem (basket : Basket , productItemId : String ) : Status The function is called before a basket item is removed.
|
Sample
REQUEST:
DELETE /dw/shop/v15_9/baskets/ceK4aiWbN132MaaadkYERkclwC/items/cerZoiWbN1K2Yaaadk6URkclwC
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match: 9b34c3ec400cd2aa6d5c4da065ab49c2cf3c1141a2f6622dff6b76cc77454cfa
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"product_items" :
[
{
"_type" : "product_item",
"adjusted_tax" : 5.00,
"base_price" : 15.99,
"bonus_product_line_item" : false,
"item_text" : "Simple Product",
"price" : 15.99,
"price_after_item_discount" : 15.99,
"price_after_order_discount" : 15.99,
"product_id" : "SimpleProduct",
"product_name" : "Simple Product",
"quantity" : 1.00,
"shipment_id" : "me",
"tax" : 5.00,
"tax_basis" : 15.99,
"tax_class_id" : null,
"tax_rate" : 0.05,
"item_id" : "ce0dwiWbN132QaaadkYERkclwC"
}
],
...
}
# in case of validation failure - example response in case of registered customer scenario when the basket's customer id does not match the authenticated customer id:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "InvalidCustomerException",
"message" : "Invalid customer."
}
}
Adds a note to an existing basket.
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/notes
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 |
---|---|---|---|
basket_id | String | The id of the basket to be modified. | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Sample
#
# Example: Add a note to a basket
#
REQUEST:
POST /dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/notes
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"subject" : "this is an example subject",
"text" : "This is a note because the customer was not very happy."
}
# 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
ETag: eaed36b37b7ba3f9f4550d9f76754fe58f2274244cc0b387e6820cae69c9c86e
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
"_v" : "15.9",
"_type" : "basket",
...
"notes" : {
"link" : "https://www.example.com/dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/notes"
}
...
}
Retrieves notes for a basket.
Url
GET https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/notes
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 |
---|---|---|---|
basket_id | String | The id of the basket for which you want to retrieve the notes. | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Sample
REQUEST:
GET /dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/notes HTTP/1.1
Host: example.com
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 158
{
"_v" : "15.9",
"_type" : "notes_result",
"notes" :
[
{
"subject" : "subject1",
"text" : "text1"
},
{
"subject" : "subject2",
"text" : "text2"
}
]
}
Adds a payment instrument to a basket.
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/payment_instruments
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
BasketPaymentInstrumentRequest
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
basket_id | String | the basket id | 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 |
InvalidPaymentMethodIdException
|
paymentMethodId (String) |
Indicates that the provided payment method is invalid or not applicable. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or the payment instrument with the given customer payment instrument id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostPaymentInstrument
|
afterPostPaymentInstrument (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status The function is called after payment instrument adding to a basket.
|
dw.ocapi.shop.basket.beforePostPaymentInstrument
|
beforePostPaymentInstrument (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status The function is called before payment instrument adding to a basket.
|
Sample
REQUEST:
POST /dw/shop/v15_9/baskets/cgUZoiWbN19xdaaaekBrRkclwC/payment_instruments
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"amount" : 1.0,
"payment_card" : {
"number":"411111111111111",
"security_code":"121",
"holder":"John Doe",
"card_type":"Visa",
"expiration_month":1,
"expiration_year":2021
},
"payment_method_id" : "CREDIT_CARD",
"c_strValue":"any custom value"
}
# 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" : "15.9",
"_type" : "basket",
...
"payment_instruments" :
[
{
"_type" : "order_payment_instrument",
"amount" : 1.00,
"etag" : "0ebd1fb7ef5dafdf46871a4edd37b98abf80f4408b4e320685a54478ba5d8f30",
"payment_card" :
{
"_type" : "payment_card",
"card_type" : "Visa",
"credit_card_expired" : false,
"expiration_month" : 1,
"expiration_year" : 2021,
"holder" : "John Doe",
"masked_number" : "***********1111",
"number_last_digits" : "1111"
},
"payment_method_id" : "CREDIT_CARD",
"payment_instrument_id" : "ceDUYiWbN1IkkaaadkYHRkclwC",
"c_strValue" : "any custom value"
}
],
...
}
# 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" : "15.9",
"fault" :
{
"type" : "InvalidPaymentMethodIdException",
"message" : "Payment method with id 'InvalidPaymentMethodId' not applicable."
}
}
Updates a payment instrument of a basket.
Url
PATCH https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/payment_instruments/{payment_instrument_id}
Formats
json, xml
Authentication
Name | Description |
---|---|
JWT | Authentication via Customer JWT token. |
OAuth | Authentication via OAuth token. |
Request Document
BasketPaymentInstrumentRequest
Response Document
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
basket_id | String | the basket id | minLength=1 |
payment_instrument_id | String | the id of the payment instrument to be updated | 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 |
InvalidPaymentMethodIdException
|
paymentMethodId (String) |
Indicates that the provided payment method is invalid or not applicable. |
400 |
PaymentInstrumentPermanentlyMaskedException
|
paymentInstrumentId (String) |
Indicates that the basket payment instrument with the given id already is permanently masked. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or the payment instrument with the given payment instrument number is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPatchPaymentInstrument
|
afterPatchPaymentInstrument (basket : Basket , paymentInstrument : OrderPaymentInstrument , paymentInstrumentRequest : BasketPaymentInstrumentRequest ) : Status The function is called after updating a payment instrument of a basket.
|
dw.ocapi.shop.basket.beforePatchPaymentInstrument
|
beforePatchPaymentInstrument (basket : Basket , paymentInstrument : OrderPaymentInstrument , newPaymentInstrument : BasketPaymentInstrumentRequest ) : Status The function is called before updating a payment instrument of a basket.
|
Sample
REQUEST:
PATCH /dw/shop/v15_9/baskets/cg2N2iWbN1ApAaaaekYdekclwC/payment_instruments/cgqoaiWbN1fhsaaaek6dekclwC
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match: 9b34c3ec400cd2aa6d5c4da065ab49c2cf3c1141a2f6622dff6b76cc77454cfa
Content-Type: application/json
{
"amount" : 2.0,
"payment_card" : {
"number":"411111111111111",
"security_code":"112",
"holder":"John Doe",
"card_type":"Visa",
"expiration_month":2,
"expiration_year":2022
},
"payment_method_id" : "CREDIT_CARD"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"payment_instruments" :
[
{
"_type" : "order_payment_instrument",
"amount" : 2.00,
"etag" : "5382b65411c7b3bc380296bc7b9b0d06530ba26d759fe8e9149e38d6d7e3a07e",
"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" : "cgqoaiWbN1fhsaaaek6dekclwC"
}
],
...
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "PaymentInstrumentPermanentlyMaskedException",
"message" : "Basket payment instrument with id 'ceqRMiWbN1my2aaadkgYlkclwC' already permanently masked."
}
}
Removes a payment instrument of a basket.
Url
DELETE https://hostname:port/dw/shop/v15_9/baskets/{basket_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 |
---|---|---|---|
basket_id | String | the basket id | minLength=1 |
payment_instrument_id | String | the id of the payment instrument to be removed | 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 customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterDeletePaymentInstrument
|
afterDeletePaymentInstrument (basket : Basket ) : Status It is called after the order payment instrument is removed from the basket.
|
dw.ocapi.shop.basket.beforeDeletePaymentInstrument
|
beforeDeletePaymentInstrument (basket : Basket , delete : OrderPaymentInstrument ) : Status It is called before the order payment instrument is removed from the basket.
|
Sample
REQUEST:
DELETE /dw/shop/v15_9/baskets/cg2N2iWbN1ApAaaaekYdekclwC/payment_instruments/cgqoaiWbN1fhsaaaek6dekclwC
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match: 9b34c3ec400cd2aa6d5c4da065ab49c2cf3c1141a2f6622dff6b76cc77454cfa
Content-Type: application/json
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"payment_instruments" :
[
{
...
}
],
...
}
Gets applicable payment methods for an existing basket.
Url
GET https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/payment_methods
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 |
---|---|---|---|
basket_id | String | the basket id | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Sample
REQUEST:
GET /dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/payment_methods
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 6d762a1ad4888de31dc1a245444f084a4846c01d7e36cd09dc183adaa6fdb647
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" : "15.9",
"_type" : "payment_method_result",
"applicable_payment_methods" :
[
{
"_type" : "payment_method",
"id" : "BANK_TRANSFER",
"name" : "Bank Transfer"
},
{
"_type" : "payment_method",
"cards" :
[
{
"_type" : "payment_card_spec",
"card_type" : "Visa",
"checksum_verification_enabled" : true,
"id" : "CREDIT_CARD.Visa",
"name" : "Visa",
"number_lengths" :
[
"13",
"16"
],
"number_prefixes" :
[
"4"
],
"security_code_length" : 3
},
{
"_type" : "payment_card_spec",
"card_type" : "Master",
"checksum_verification_enabled" : true,
"id" : "CREDIT_CARD.Master",
"name" : "Master Card",
"number_lengths" :
[
"16"
],
"number_prefixes" :
[
"51-55"
],
"security_code_length" : 3
},
{
"_type" : "payment_card_spec",
"card_type" : "Amex",
"checksum_verification_enabled" : true,
"id" : "CREDIT_CARD.Amex",
"name" : "American Express",
"number_lengths" :
[
"15"
],
"number_prefixes" :
[
"34",
"37"
],
"security_code_length" : 4
}
],
"id" : "CREDIT_CARD",
"name" : "Credit Card",
"c_somestring" : "PaymentMethod String Value"
},
{
"_type" : "payment_method",
"description" : "A conditional payment method on customer group 'Unregistered'.",
"id" : "OCAPI_Payment_Unregistered",
"image" : "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
"name" : "OCAPI Payment (Unregistered)"
},
{
"_type" : "payment_method",
"description" : "A conditional payment method on country 'DE'.",
"id" : "OCAPI_Payment_DE",
"image" : "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
"name" : "OCAPI Payment (DE)"
},
{
"_type" : "payment_method",
"description" : "A simple payment method without any conditions.",
"id" : "OCAPI_Payment_Simple",
"image" : "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
"name" : "OCAPI Payment (Simple)"
}
]
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 404 NOT FOUND
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" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "No basket with id 'non_existing_basket' found."
}
}
Adds a custom manual price adjustment to the basket.
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/price_adjustments
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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | 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 |
FixedPriceAdjustmentAlreadyExistsException
|
itemId (String) level (String) |
Indicates that a fixed price adjustment was already created for the given level. |
400 |
InvalidPriceAdjustmentLevelException
|
Indicates that a fixed price adjustment was added at order level. | |
400 |
InvalidPromotionIdException
|
promotionId (String) |
Indicates that a promotion id was used twice. |
400 |
SystemPromotionIdException
|
promotionId (String) |
Indicates that a system promotion id was used as a manual promotion id. |
400 |
TooManyPromotionsException
|
Indicates that more than one hundred price adjustments would have been created. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostPriceAdjustment
|
afterPostPriceAdjustment (basket : Basket , request : PriceAdjustmentRequest ) : Status The function is called after a custom price adjustment was added.
|
dw.ocapi.shop.basket.beforePostPriceAdjustment
|
beforePostPriceAdjustment (basket : Basket , request : PriceAdjustmentRequest ) : Status The function is called before a custom price adjustment is added.
|
Sample
REQUEST:
POST /dw/shop/v15_9/baskets/cdpcIiWbO5cMcaaadlIDUtofOK/price_adjustments
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match: 9b34c3ec400cd2aa6d5c4da065ab49c2cf3c1141a2f6622dff6b76cc77454cfa
Content-Type: application/json;charset=UTF-8
{
"discount" : {
"value" : 5,
"type" : "percentage"
},
"item_text" : "MyOrderAdjustment",
"level" : "order",
"promotion_id" : "manual adjustment"
}
# 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" : "15.9",
"_type" : "basket",
...
"order_price_adjustments" :
[
{
"_type" : "price_adjustment",
"applied_discount" :
{
"_type" : "discount",
"amount" : 0.05,
"percentage" : 5,
"type" : "percentage"
},
"created_by" : "testAgent",
"creation_date" : "2015-05-25T09:13:10.942Z",
"custom" : true,
"item_text" : "MyOrderAdjustment",
"manual" : true,
"price" : -10.00,
"promotion_id" : "manual adjustment",
"price_adjustment_id" : "cdzoAiWbOmbiUaaadlfSpMDgNw"
}
],
...
}
# in case of validation failure - example response in case the user does not have a functional permission to add price adjustment:
HTTP/1.1 403 FORBIDDEN
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "UserAccessForbiddenException",
"message" : "POST"
}
}
Removes a custom manual price adjustment from the basket.
Url
DELETE https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/price_adjustments/{price_adjustment_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
price_adjustment_id | String | the uuid of the adjustment to be removed | 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 |
InvalidPriceAdjustmentItemIdException
|
priceAdjustmentId (String) |
Indicates that the priceAdjustmentId is missing, empty or whitespace. |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterDeletePriceAdjustment
|
afterDeletePriceAdjustment (basket : Basket , priceAdjustmentId : String ) : Status The function is called after a custom price adjustment was removed.
|
dw.ocapi.shop.basket.beforeDeletePriceAdjustment
|
beforeDeletePriceAdjustment (basket : Basket , priceAdjustmentId : String ) : Status The function is called before a custom price adjustment is removed.
|
Sample
REQUEST:
DELETE /dw/shop/v15_9/baskets/cdpcIiWbO5cMcaaadlIDUtofOK/price_adjustments/cd0PQiWbO5xrQaaadllDYtofOK
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
If-Match: 9b34c3ec400cd2aa6d5c4da065ab49c2cf3c1141a2f6622dff6b76cc77454cfa
Content-Type: application/json;charset=UTF-8
# in case of success when a product item price adjustment is deleted:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"_type" : "basket",
...
"product_items" :
[
{
"_type" : "product_item",
"adjusted_tax" : 10.00,
"base_price" : 15.99,
"bonus_product_line_item" : false,
"item_text" : "Simple Product",
"price" : 115.98,
"price_after_item_discount" : 115.98,
"price_after_order_discount" : 115.98,
"product_id" : "SimpleProduct",
"product_name" : "Simple Product",
"quantity" : 2.00,
"shipment_id" : "me",
"tax" : 10.00,
"tax_basis" : 115.98,
"tax_class_id" : null,
"tax_rate" : 0.05,
"item_id" : "dgHc6iWbO57GEaaaeldnYtofOK"
}
],
...
}
# in case of validation failure - example response in case the user does not have a functional permission to delete price adjustment:
RESPONSE:
HTTP/1.1 403 FORBIDDEN
{
"_v" : "15.9",
"fault" :
{
"type" : "UserAccessForbiddenException",
"message" : "DELETE"
}
}
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/shipments
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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | 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 |
MissingShipmentIdException
|
Indicates that a shipment id is not provided. | |
400 |
DuplicateShipmentIdException
|
shipmentId (String) |
Indicates that a shipment with the provided id already exists for the basket. |
400 |
DuplicateShipmentNoException
|
shipmentNo (String) |
Indicates that a shipment with the provided shipment number already exists for the basket. |
400 |
InvalidShippingMethodException
|
Indicates that a shipping method with an id was specified which is not a valid shipping method id. | |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostShipment
|
afterPostShipment (basket : Basket , shipment : Shipment ) : Status The function is called after the creation of a shipment for a basket.
|
dw.ocapi.shop.basket.beforePostShipment
|
beforePostShipment (basket : Basket , shipment : Shipment ) : Status The function is called before the creation of a shipment for a basket.
|
Sample
#
# Example: Create a shipment for a basket
#
REQUEST:
POST /dw/shop/v15_9/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/shipments
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: c38827d469cda8bd04edd769df6d9295615ffe0f20e34bd4c0426b6739c3221c
Content-Type: application/json; charset=UTF-8
{
"gift":true,
"gift_message":"Happy Birthday, Sværre",
"id": "StandardShipping",
"shipping_method":
{
"id":"BaseShippingMethod"
},
"shipping_address" :
{
"first_name":"John",
"last_name":"Smith",
"city":"Boston",
"country_code":"US",
},
"c_somestring":"shipment_custom_property"
}
# 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
ETag: eaed36b37b7ba3f9f4550d9f76754fe58f2274244cc0b387e6820cae69c9c86e
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
"_v" : "15.9",
...
"shipments": [
{
"gift": true,
"gift_message", "Happy Birthday, Sværre",
"id": "StandardShipping",
"shipping_address":
{
"city": "Boston",
"country_code": "US",
"first_name": "John",
"full_name": "John Smith",
"last_name": "Smith",
"c_strValue" : "cTest"
},
"shipping_method":
{
"description" : "The base shipping method.",
"id" : "BaseShippingMethod",
"name" : "Base Shipping Method",
"price" : 5.55
},
"shipment_id": "deQcx9aaabfGQaaadiAZ6KZFcl",
"c_somestring" : "shipment_custom_property"
}
],
...
}
# in case of validation failure - example response when the shipping method is not existing or is not applicable:
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": "15.9",
"fault": {
"details": {
"validation.type": "InvalidShippingMethod",
"validation.message": "Shipping method 'NotExistingMethodId' not applicable"
},
"type": "InvalidShippingMethodIdException",
"message": "Shipping method 'NotExistingMethodId' not applicable"
}
}
Url
PATCH https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/shipments/{shipment_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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
shipment_id | String | 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 |
InvalidShipmentIdException
|
shipmentId (String) |
Indicates that the given shipment id was invalid. |
400 |
DuplicateShipmentIdException
|
shipmentId (String) |
Indicates that a shipment with the provided id already exists for the basket. |
400 |
DuplicateShipmentNoException
|
shipmentNumber (String) |
Indicates that a shipment with the provided shipment number already exists for the basket. |
400 |
InvalidShippingMethodException
|
Indicates that a shipping method with an id was specified which is not a valid shipping method id. | |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostShipment
|
afterPostShipment (basket : Basket , shipment : Shipment ) : Status The function is called after the creation of a shipment for a basket.
|
dw.ocapi.shop.basket.beforePostShipment
|
beforePostShipment (basket : Basket , shipment : Shipment ) : Status The function is called before the creation of a shipment for a basket.
|
Sample
#
# Example: Update a shipment of a basket
#
REQUEST:
PATCH /shop/v15_9/baskets/cdHyF9aacbudgaaadl5x7bVp1i/shipments/cdL6b9aacbUNAaaadlbiBbVp1i
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: c38827d469cda8bd04edd769df6d9295615ffe0f20e34bd4c0426b6739c3221c
Content-Type: application/json; charset=UTF-8
{
"c_somestring":"shipment_custom_property",
"gift":true,
"gift_message": "Happy Birthday, Sværre"
}
# in case of success:
RESPONSE:
Date:Mon, 04 May 2015 07:18:49 GMT
Server:B2C Commerce Server/2.4.10 (Unix) OpenSSL/1.0.1f
Content-Length:2815
ETag:c4fbe17556b411fa79f4c3d517a2f160a521509aeb3e9170048cf7b617c97c8c
Keep-Alive:timeout=15, max=97
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
{
"_v" : "15.9",
...
"shipments": [
{
"gift":true,
"gift_message":"Happy Birthday, Sværre",
"id": "StandardShipping",
"shipping_address":
{
"city": "Boston",
"country_code": "US",
"first_name": "John",
"full_name": "John Smith",
"last_name": "Smith",
},
"shipment_no" : "me",
"shipping_method":
{
"description" : "The base shipping method.",
"id" : "BaseShippingMethod",
"name" : "Base Shipping Method",
"price" : 5.55
},
"shipment_id": "cdL6b9aacbUNAaaadlbiBbVp1i",
"c_somestring" : "shipment_custom_property"
}
],
...
}
# in case of validation failure - example response when the shipping method is not existing or is not applicable:
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": "15.9",
"fault": {
"details": {
"validation.type": "InvalidShippingMethod",
"validation.message": "Shipping method 'NotExistingMethodId' not applicable"
},
"type": "InvalidShippingMethodIdException",
"message": "Shipping method 'NotExistingMethodId' not applicable"
}
}
Sets a shipping address of a specific shipment of a basket.
Url
PUT https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/shipments/{shipment_id}/shipping_address?use_as_billing={Boolean}&customer_address_id={String}
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 |
---|---|---|---|
basket_id | String | The id of the basket to be modified. | minLength=1 |
shipment_id | String | The id of the shipment to be modified. | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
customer_address_id | String | The id of the customer address to be set as shipping address. Cannot be used together with an existing body. | minLength=1 |
use_as_billing | Boolean | The flag indicating whether the given address will also be used as billing address. |
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 |
CustomerAddressIdNotApplicableException
|
Indicates that both customer_address_id and address body was provided. | |
400 |
InvalidShipmentIdException
|
shipmentId (String) |
Thrown if the shipment with the given shipment id is unknown. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token (not relevant when using OAuth). | |
400 |
InvalidCustomerException
|
Indicates that an customerAddressId was provided but either an anonymous or no customer was set. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or that the address specified by customer_address_id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPutShippingAddress
|
afterPutShippingAddress (basket : Basket , shipment : Shipment , shippingAddress : OrderAddress ) : Status The function is called after setting of the shipping address to a certain shipment of the basket.
|
dw.ocapi.shop.basket.beforePutShippingAddress
|
beforePutShippingAddress (basket : Basket , shipment : Shipment , shippingAddress : OrderAddress ) : Status The function is called before setting of the shipping address to a certain shipment of the basket.
|
Sample
REQUEST:
PUT /dw/shop/v15_9/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/shipments/shipmentId123/shipping_address
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
"first_name":"John",
"last_name":"Smith",
"city":"Boston",
"country_code":"US",
"c_strValue":"cTest"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"shipments" :
[
{
"_type" : "shipment",
"id" : "me",
"shipping_method" :
{
"_type" : "shipping_method",
"description" : "The default shipping method.",
"id" : "DefaultShippingMethod",
"name" : "Default Shipping Method",
"price" : 5.55,
"c_somestring" : "ShippingMethod String Value"
},
"shipment_id" : "cdKeciWbNL21saaadjZkbNt6xg"
},
{
"_type" : "shipment",
"id" : "shipmentId123",
"shipping_address" :
{
"_type" : "order_address",
"city" : "Boston",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Smith",
"last_name" : "Smith",
"c_strValue" : "cTest"
},
"shipment_id" : "cdOlsiWbNLWhkaaadjbQdNt6xg"
}
],
...
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 409 CONFLICT
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" : {
"type" : "IfMatchRequiredException",
"message" : "If-Match header is required, but no one was provided. Please provide an If-Match header."
}
}
REQUEST:
PUT /dw/shop/v15_9/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/shipments/shipmentId123/shipping_address?customer_address_id=homeaddress
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json
{
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"shipments" :
[
{
"_type" : "shipment",
"id" : "me",
"shipping_method" :
{
"_type" : "shipping_method",
"description" : "The default shipping method.",
"id" : "DefaultShippingMethod",
"name" : "Default Shipping Method",
"price" : 5.55,
"c_somestring" : "ShippingMethod String Value"
},
"shipment_id" : "cdKeciWbNL21saaadjZkbNt6xg"
},
{
"_type" : "shipment",
"id" : "shipmentId123",
"shipping_address" :
{
"_type" : "order_address",
"city" : "Boston",
"country_code" : "US",
"first_name" : "John",
"full_name" : "John Smith",
"last_name" : "Smith",
"c_strValue" : "cTest"
},
"shipment_id" : "cdOlsiWbNLWhkaaadjbQdNt6xg"
}
],
...
}
Sets a shipping method to a specific shipment of a basket.
Url
PUT https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/shipments/{shipment_id}/shipping_method
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 |
---|---|---|---|
basket_id | String | the id of the basket to be modified | minLength=1 |
shipment_id | String | the id of the shipment to be modified | 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 |
InvalidShippingMethodException
|
Indicates that a shipping method with the given shipping method id is unknown or non-applicable for that shipment. | |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPutShippingMethod
|
afterPutShippingMethod (basket : Basket , shipment : Shipment , shippingMethod : ShippingMethod ) : Status The function is called after setting of the shipping method to a certain shipment of the basket.
|
dw.ocapi.shop.basket.beforePutShippingMethod
|
beforePutShippingMethod (basket : Basket , shipment : Shipment , shippingMethod : ShippingMethod ) : Status The function is called before setting of the shipping method to a certain shipment of the basket.
|
Sample
REQUEST:
PUT /dw/shop/v15_9/baskets/cdqwkiWbPdFlkaaadh8xRczLvx/shipments/shipmentId1/shipping_method
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: bc4a4ccad0b74fdcc106e536105f05408bd7d324bf094b3676a6f22ae4dc894c
Content-Type: application/json
{
"id":"BaseShippingMethod"
}
# in case of success:
RESPONSE:
HTTP/1.1 200 OK
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
...
"shipments" :
[
{
"_type" : "shipment",
"id" : "me",
"shipping_method" :
{
"_type" : "shipping_method",
"description" : "The default shipping method.",
"id" : "DefaultShippingMethod",
"name" : "Default Shipping Method",
"price" : 5.55
},
"shipment_id" : "cd5vaiWbNRZfwaaadknaASga38"
},
{
"_type" : "shipment",
"id" : "shipmentId1",
"shipping_method" :
{
"_type" : "shipping_method",
"description" : "The base shipping method.",
"id" : "BaseShippingMethod",
"name" : "Base Shipping Method",
"price" : 0.01
},
"shipment_id" : "cd83AiWbNR0yMaaadkAoASga38"
}
],
...
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"fault" :
{
"type" : "InvalidShippingMethodException",
"message" : "Shipping method 'BaseShippingMethod2' not applicable"
...
}
}
Gets the applicable shipping methods for a certain shipment of a basket.
Url
GET https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/shipments/{shipment_id}/shipping_methods
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 |
---|---|---|---|
basket_id | String | the id of the basket | minLength=1 |
shipment_id | String | the id of the shipment | minLength=1 |
In case of a failure Fault Document is returned.
Faults
Status | Type | Arguments | Description |
---|---|---|---|
400 |
InvalidShipmentIdException
|
shipmentId (String) |
Indicates that the given shipment id is invalid. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown or the shipment with the given shipment id is unknown. |
Sample
REQUEST:
GET /dw/shop/v15_9/baskets/this/shipments/me/shipping_methods
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 6d762a1ad4888de31dc1a245444f084a4846c01d7e36cd09dc183adaa6fdb647
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" : "15.9",
"_type" : "shipping_method_result",
"applicable_shipping_methods" :
[
{
"_type" : "shipping_method",
"description" : "The default shipping method.",
"id" : "DefaultShippingMethod",
"name" : "Default Shipping Method",
"price" : 5.55
},
{
"_type" : "shipping_method",
"description" : "The base shipping method.",
"id" : "BaseShippingMethod",
"name" : "Base Shipping Method",
"price" : 0.99
},
{
"_type" : "shipping_method",
"description" : "A shipping method that contains product level shipping costs.",
"id" : "ProductLevelShippingCostsShippingMethod",
"name" : "Product Level Shipping Costs Shipping Method",
"price" : 0.10
}
],
"default_shipping_method_id" : "DefaultShippingMethod"
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 404 NOT FOUND
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" : "15.9",
"fault" :
{
"type" : "NotFoundException",
"message" : "No shipment with id 'non-existingShipmentId' for basket 'cddKMiWbNOUsQaaadkIvMbpEJ0' found."
}
}
Url
POST https://hostname:port/dw/shop/v15_9/baskets/{basket_id}/submit
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 |
---|---|---|---|
basket_id | String | The id of the basket to be used for the order creation. | 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 |
GiftCertificateCreationException
|
Thrown if a failure during the creation of a gift certificate for a gift certificate item. | |
400 |
InvalidShippingAddressException
|
shipmentId (String) |
Indicates an empty or invalid shipping address. |
400 |
InvalidCouponItemException
|
couponCode (String) |
Indicates an invalid coupon code. |
400 |
InvalidShippingMethodException
|
Indicates an empty or invalid shipping method. | |
400 |
InvalidBillingAddressException
|
Indicates an empty or invalid billing address. | |
400 |
InvalidPaymentMethodException
|
paymentMethodId (String) |
Thrown if a missing or invalid payment method. |
400 |
InvalidProductItemException
|
productId (String) |
Indicates an invalid product item. |
400 |
InvalidProductItemPriceException
|
productId (String) |
Indicates an invalid product item price. |
400 |
InvalidOptionItemException
|
Indicates an invalid product option item or option item value. | |
400 |
InvalidProductOptionItemPriceException
|
optionId (String) |
Indicates an invalid product option item price. |
400 |
ProductItemNotAvailableException
|
productId (String) quantity (Decimal) |
Thrown if a product item is not available. |
400 |
InvalidCustomerException
|
Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth. | |
404 |
NotFoundException
|
Indicates that the basket with the given basket id is unknown. |
Customization
This Resource supports server-side customization.
Extension Point | Method Detail |
---|---|
dw.ocapi.shop.basket.afterPostSubmit
|
afterPostSubmit (order : Order ) : Status The function is called after a basket is submitted.
|
dw.ocapi.shop.basket.beforePostSubmit
|
beforePostSubmit (basket : Basket ) : Status The function is called before a basket is submitted.
|
Sample
REQUEST:
POST /dw/shop/v15_9/baskets/cdxEQiWbNVZZaaaadhKBc35gtp/submit
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 6d762a1ad4888de31dc1a245444f084a4846c01d7e36cd09dc183adaa6fdb647
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
Expires: Thu, 01-Jan-1970 00:00:00 GMT
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8
{
"_v" : "15.9",
"adjusted_merchandize_total_tax" : 0.05,
"adjusted_shipping_total_tax" : 0.00,
"billing_address" : {
"city" : "Boston",
"country_code" : "US",
"first_name" : "Jeff",
"full_name" : "Jeff Lebowski",
"last_name" : "Lebowski",
"c_strValue" : "cTest"
},
"creation_date" : "2014-11-06T13:36Z",
"currency" : "USD",
"customer_info" : {
"customer_no" : "jlebowski",
"email" : "[email protected]"
},
"merchandize_total_tax" : 5.00,
"order_no" : "00000101",
"order_token" : "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
"order_total" : 1.06,
"payment_instruments" : [
{
"amount" : 1.00,
"payment_bank_account" : {
"drivers_license_last_digits" : "ense",
"drivers_license_masked" : "**************ense",
"number_last_digits" : "mber",
"number_masked" : "*************mber"
},
"id" : "cdKCIiWbNVndQaaadhlSa35gtp",
"payment_card" : {
"card_type" : "testVisa",
"credit_card_expired" : false,
"expiration_month" : 4,
"expiration_year" : 2018,
"holder" : "TestPerson",
"number_last_digits" : "mber",
"number_masked" : "**********mber"
},
"payment_method_id" : "OCAPI_Payment_Simple"
}
],
"product_items" : [
{
"adjusted_tax" : 5.00,
"base_price" : 15.99,
"bonus_product_line_item" : false,
"item_text" : "Simple Product",
"price" : 15.99,
"price_after_item_discount" : 15.99,
"price_after_order_discount" : 1.00,
"product_id" : "SimpleProduct",
"product_name" : "Simple Product",
"quantity" : 1.00,
"tax" : 5.00,
"tax_basis" : 15.99,
"tax_class_id" : null,
"tax_rate" : 0.05,
"item_id" : "cdHBEiWbNV9ZcaaadhrCk35gtp",
"c_strValue" : "Test"
}
],
"product_sub_total" : 15.99,
"product_total" : 1.00,
"shipments" : [
{
"id" : "me",
"shipping_address" : {
"city" : "Boston",
"country_code" : "US",
"first_name" : "Jeff",
"full_name" : "Jeff Lebowski",
"last_name" : "Lebowski",
"c_strValue" : "cTest"
},
"shipping_method" : {
"description" : {
"default" : "The base shipping method."
},
"id" : "BaseShippingMethod",
"name" : {
"default" : "Base Shipping Method"
},
"price" : 0.01,
"c_somestring" : "ShippingMethod String Value"
}
}
],
"shipping_items" : [
{
"adjusted_tax" : 0.00,
"base_price" : 0.01,
"item_text" : "Shipping",
"price" : 0.01,
"price_after_item_discount" : 0.01,
"shipment_id" : "me",
"tax" : 0.00,
"tax_basis" : 0.01,
"tax_class_id" : "DefaultTaxClass",
"tax_rate" : 0.05,
"item_id" : "devgoiWbNVc92aaadhrSk35gtp"
}
],
"shipping_total" : 0.01,
"shipping_total_tax" : 0.00,
"status" : "created",
"tax_total" : 0.05,
"c_strValue" : "before submit basket",
"c_textValue" : "after submit basket"
}
# in case of validation failure:
RESPONSE:
HTTP/1.1 404 NOT FOUND
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" : "15.9",
"fault" : {
"type" : "NotFoundException",
"message" : "No basket with id '123' found."
}
}