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

Baskets resource (Shop API 23.2)

Summary

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:
  • customer information: PUT /baskets/{basket_id}/customer
  • billing address: PUT /baskets/{basket_id}/billing_address
  • shipments including shipping address and shipping method: POST /baskets/{basket_id}/shipments
  • product items: POST /baskets/{basket_id}/items
  • coupon items: POST /baskets/{basket_id}/coupons
  • Invalid coupons are silently ignored.
  • gift certificate items: POST /baskets/{basket_id}/gift_certificates
  • payment method and card type: POST /baskets/{basket_id}/payment_instruments
  • custom properties: PATCH /baskets/{basket_id}
Related resource means with which resource you can specify the same data after the basket creation. Identify the basket using the basket_id property, which should be integrated into the path of an update request, for example a POST to /baskets/{basket_id}/items. The resource supports JWT or OAuth tokens for authentication:
  • A customer must provide a JWT, which specifies exactly one customer (it may be a guest or a registered customer). In this case the resource creates a basket for this customer.
  • An agent must provide an OAuth token. The agent can use this resource to create a basket for a new created guest customer, and can later update the customer if desired.
The number of baskets which can be created per customer is limited. When a basket is created it is said to be open. It remains open until either an order is created from it using a POST to resource /orders or it is deleted using a DELETE to resource /baskets/{basket_id}. The number of open baskets allowed depends on the authentication method used:
  • When using JWT each customer can have just one open basket.
  • When using OAuth each customer can have up to 4 open baskets.
Custom properties in the form c_<CUSTOM_NAME> are supported. A custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for the Basket system object, and its value must be valid for that custom attribute. Other basket properties like the channel type or source code cannot be set with this resource.
POST /baskets/reference Creates a new basket based on a basket reference.

The returned basket will be a copy of the basket in the reference. The basket in the reference must be a basket of a guest customer and the provided customer_id in the reference must match the guest customer in the basket. There is a check that an authenticated customer for whom a basket is being copied doesn't already have a basket. In case customer_id not matching a BasketNotFoundException will be returned as fault. All personal data like payment instruments and coupons will not be copied over to the new basket. When authenticated via JWT, a customer can only have one open basket and a CustomerBasketsQuotaExceededException is thrown, when the customer tries to create a second basket. Before using this endpoint to create a basket for a JWT-authenticated customer, verify that they don't already have one.

GET /baskets/{basket_id} Gets a basket.
PATCH /baskets/{basket_id} Updates a basket. Only the currency of the basket, source code, 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}/agent Marks a basket as an agent basket.
GET /baskets/{basket_id}/approaching_discounts Gets the approaching discounts of 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.
DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id} Deletes a gift certificate item from an existing basket.
PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id} Updates a gift certificate item of an existing basket.
POST /baskets/{basket_id}/items Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are:
  • product_id: a valid product id. This is the id of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference.
  • shipment_id: a valid shipment id (optional). This is the id of the shipment in which the product item is created.
  • quantity: a number between 0.01 and 999. This is the quantity of the product to order.
  • inventory_id: a valid inventory id (optional). This is the id of the inventory from which the item is allocated.
  • bonus_discount_line_item_id: a valid bonus discount line item id (optional). This is the id of the bonus discount line item for which the added product is a selected bonus product.
  • option_items/option_value_id: a valid option value id. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the 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.
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem.
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:
  • 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.
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.
DELETE /baskets/{basket_id}/notes/{note_id} Removes a basket note.
POST /baskets/{basket_id}/payment_instruments Adds a payment instrument to a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See POST /orders/{order_no}/payment_instruments and PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}. NOTE: If CREDIT_CARD is selected as the payment_method_id, it is mandatory to provide the property card_type.

PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id} Updates a payment instrument of a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See POST /orders/{order_no}/payment_instruments and PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}

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 considering the open payment amount only.
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.
PATCH /baskets/{basket_id}/price_adjustments/{price_adjustment_id} Updates a custom manual price adjustment on the basket. Only the following PATH values are considered for the update: discount, item_text, reason_code and custom properties; all other attributes are ignored. The discount type of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type PERCENTAGE, the 'percentage' attribute is mandatory. For adjustments of type AMOUNT and FIXED_PRICE, the 'amount' attribute is mandatory.
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:
  • the id
  • the shipping address
  • the shipping method
  • gift boolean flag
  • gift message
  • custom properties
PATCH /baskets/{basket_id}/shipments/{shipment_id} Updates a shipment for a basket. The body can include updated values for the following properties:
  • the id
  • the shipping address
  • the shipping method
  • gift boolean flag
  • gift message
  • custom properties
DELETE /baskets/{basket_id}/shipments/{shipment_id} Removes a specified shipment and all associated product, gift certificate, shipping and price adjustment line items from a basket. You can't remove a default shipment (id = "me").
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.
PUT /baskets/{basket_id}/storefront Marks a basket as storefront basket.

Create basket

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:
  • customer information: PUT /baskets/{basket_id}/customer
  • billing address: PUT /baskets/{basket_id}/billing_address
  • shipments including shipping address and shipping method: POST /baskets/{basket_id}/shipments
  • product items: POST /baskets/{basket_id}/items
  • coupon items: POST /baskets/{basket_id}/coupons
  • Invalid coupons are silently ignored.
  • gift certificate items: POST /baskets/{basket_id}/gift_certificates
  • payment method and card type: POST /baskets/{basket_id}/payment_instruments
  • custom properties: PATCH /baskets/{basket_id}
Related resource means with which resource you can specify the same data after the basket creation. Identify the basket using the basket_id property, which should be integrated into the path of an update request, for example a POST to /baskets/{basket_id}/items. The resource supports JWT or OAuth tokens for authentication:
  • A customer must provide a JWT, which specifies exactly one customer (it may be a guest or a registered customer). In this case the resource creates a basket for this customer.
  • An agent must provide an OAuth token. The agent can use this resource to create a basket for a new created guest customer, and can later update the customer if desired.
The number of baskets which can be created per customer is limited. When a basket is created it is said to be open. It remains open until either an order is created from it using a POST to resource /orders or it is deleted using a DELETE to resource /baskets/{basket_id}. The number of open baskets allowed depends on the authentication method used:
  • When using JWT each customer can have just one open basket.
  • When using OAuth each customer can have up to 4 open baskets.
Custom properties in the form c_<CUSTOM_NAME> are supported. A custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for the Basket system object, and its value must be valid for that custom attribute. Other basket properties like the channel type or source code cannot be set with this resource.

Url

POST https://hostname:port/dw/shop/v23_2/baskets

Formats

json, xml

Authentication

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

Request Document

Basket

Response Document

Basket

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, not relevant when using OAuth.
400 CustomerBasketsQuotaExceededException

basketIds (String)

 Thrown if a new basket cannot be created because the maximum number of baskets per customer would 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 ShipmentNotFoundException

shipmentId (String)

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

beforePOST_v2 (basketRequest : Basket ) : Status

The function is called before the request will be processed.

Parameters:
basketRequest - the basket request
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.afterPOST

afterPOST (basket : Basket ) : Status

The function is called after the basket was created.

Parameters:
basket - the created basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket ) : Status

Parameters:
basket - the created basket
basketResponse - basket response object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

# create a basket with the given token

REQUEST:
POST /dw/shop/v23_2/baskets HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
Content-Length: 0

# in case of success, response contains new created basket with its ID and resource state

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

Create a basket from a reference

Creates a new basket based on a basket reference.

The returned basket will be a copy of the basket in the reference. The basket in the reference must be a basket of a guest customer and the provided customer_id in the reference must match the guest customer in the basket. There is a check that an authenticated customer for whom a basket is being copied doesn't already have a basket. In case customer_id not matching a BasketNotFoundException will be returned as fault. All personal data like payment instruments and coupons will not be copied over to the new basket. When authenticated via JWT, a customer can only have one open basket and a CustomerBasketsQuotaExceededException is thrown, when the customer tries to create a second basket. Before using this endpoint to create a basket for a JWT-authenticated customer, verify that they don't already have one.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/reference

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.

Request Document

BasketReference

Response Document

Basket

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 BasketNotFoundException

basketId (String)

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

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.reference.beforePOST

beforePOST (sourceBasket : Basket , request : BasketReference ) : Status

Parameters:
sourceBasket - the basket to copy the data from
basketReferenceRequest - the basket reference input document
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.reference.afterPOST

afterPOST (sourceBasket : Basket , basket : Basket , request : BasketReference ) : Status

Parameters:
sourceBasket - the basket to copy the data from
basket - the created basket
basketReferenceRequest - the basket reference input document
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.reference.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , basketReferenceRequest : BasketReference ) : Status

Parameters:
basket - the created basket
basketResponse - the basket response object
basketReferenceRequest - the basket reference input document
Returns:
a non-null Status ends the hook execution

Sample

# create a basket with the given token and copy data from referenced guest basket

REQUEST:
POST /dw/shop/v23_2/baskets_reference HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
{
  "basket_id" :"tczFTaOjgEqUkacedkvHwbgrP3",
  "customer_id" : "dlNJrbxJovaT5TPxUSfOywk6as"
}

# in case of success, response contains new created basket with its id and resource state

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
   "_flash" : 
   [
...  
   ]
...
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   "currency" : "USD",
   "customer_info" : 
   {
      "_type" : "customer_info",
      "customer_id" : "adNJrbxJovaT5DPxUSfOywk6Et",
      "email" : ""
   },
...
}

Get basket

Gets a basket.

Url

GET https://hostname:port/dw/shop/v23_2/baskets/{basket_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

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

beforeGET (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the basket id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.modifyGETResponse

modifyGETResponse (basket : Basket , basketResponse : Basket ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

# get a basket by id, request includes Authorization:Bearer token

REQUEST:
GET /dw/shop/v23_2/baskets/bczFTaOjgEqUkaaadkvHwbgrP5 HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   "currency" : "USD",
   "channel_type" : "callcenter"
...
}

# in case basket for given ID not found

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID 'xxbcql1aOjgEsaaadkOtMbgrQq' could be found."
   }
}

Update the customer of a basket

Updates a basket. Only the currency of the basket, source code, and the custom properties of the basket and of the shipping items will be considered.

Url

PATCH https://hostname:port/dw/shop/v23_2/baskets/{basket_id}

Formats

json, xml

Authentication

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

Request Document

Basket

Response Document

Basket

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
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
400 UnsupportedCurrencyException

currency (String)

 Indicates that the basket cannot be updated because the requested currency is not supported by the site.
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.
400 SourceCodeInactiveException

sourceCode (String)

 Indicates that the provided code is not currently active.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 ShippingItemNotFoundException

shippingItemId (String)

 Indicates that the shipping item with the given item id is unknown for the basket
404 SourceCodeNotFoundException

sourceCode (String)

 Indicates that the provided code was not found.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.beforePATCH

beforePATCH (basket : Basket , basketInput : Basket ) : Status

The function is called before updating of the basket.

Parameters:
basket - the basket to be updated
basketInput - the basket delta containing the desired changes
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.afterPATCH

afterPATCH (basket : Basket , basketInput : Basket ) : Status

The function is called after updating of the basket.

Parameters:
basket - the basket which was updated
basketInput - the basket delta containing the desired changes
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v23_2/baskets/bczFTaOjgEqUkaaadkvHwbgrP5 HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
{
   "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
   "c_newCustomProperty:"customValue"
}
# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "23.2",
   "fault" : 
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID 'xxbcql1aOjgEsaaadkOtMbgrQq' could be found."
   }
}

Remove a basket

Removes a basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}

Formats

json, xml

Authentication

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

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

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

beforeDELETE (basket : Basket ) : Status

The function is called before removing a basket.

Parameters:
basket - the basket to be removed
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.afterDELETE

afterDELETE (basketId : String ) : Status

The function is called after removing a basket.

Parameters:
basketId - the identifier of the removed basket
Returns:
a non-null Status ends the hook execution

Sample

# remove a basket by id, request includes Authorization:Bearer token

REQUEST:
DELETE /dw/shop/v23_2/baskets/bczFTaOjgEqUkaaadkvHwbgrP5 HTTP/1.1
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success

RESPONSE:
HTTP/1.1 204 NO CONTENT

# validation failure in case of an unknown basket id:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID '123' could be found."
   }
}

Put a basket as agent basket.

Marks a basket as an agent basket.

Url

PUT https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/agent

Formats

json, xml

Authentication

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

Response Document

Basket

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 CustomerBasketsQuotaExceededException

basketIds (String)

 Indicates that marking this basket as an agent basket would exceed the open agent basket limit for the basket customer
404 BasketNotFoundException

basketId (String)

 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.agent.beforePUT

beforePUT (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the basket id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.agent.afterPUT

afterPUT (basket : Basket ) : Status

The function is called after a put of a basket as an agent basket.

Parameters:
basket - the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.agent.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/123324d33edew2443/agent HTTP/1.1
Host: example.com
Authorization: Bearer xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Content-Type: application/json


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
  "basket_id" : "bcRTDaOjgyscwaaadkrhhQHmrP",
  "agent_basket": true,
...
}

Get approaching discounts of a basket

Gets the approaching discounts of a basket

Url

GET https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/approaching_discounts

Formats

json, xml

Authentication

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

Response Document

ApproachingDiscountResult

Path Parameters

Parameter Type Description Constraints
basket_id String The id of the basket to be checked. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 BasketNotFoundException

basketId (String)

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

beforeGET (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the basket id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.approaching_discounts.modifyGETResponse

modifyGETResponse (approachingDiscountResultResponse : ApproachingDiscountResult ) : Status

Parameters:
approachingDiscountResultResponse - approaching discount result response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/baskets/bczFTaOjgEqUkaaadkvHwbgrP5/approaching_discounts HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_type" : "approaching_discount_result",
   "approaching_discounts" : [
      {
         "_type" : "approaching_discount",
         "condition_threshold" : 100.00,
         ...
         "type" : order
      },
      ...
   ]
}

# in case basket for given id not found

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

{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with id 'xxbcql1aOjgEsaaadkOtMbgrQq' found."
   }
}

Set billing address of a basket

Sets the billing address of a basket.

Url

PUT https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/billing_address?use_as_shipping={Boolean}&customer_address_id={String}

Formats

json, xml

Authentication

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

Request Document

OrderAddress

Response Document

Basket

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 (not relevant when using OAuth).
400 EmptyBillingAddressException   Indicates that the billing address was null and no customer_address_id was provided.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 AddressNotFoundException

addressName (String)

 Indicates 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.billing_address.beforePUT

beforePUT (basket : Basket , billingAddress : OrderAddress ) : Status

The function is called before setting of the billing address to the basket.

Parameters:
basket - the basket based on which the order is created
billingAddress - the billing address to be set to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.billing_address.afterPUT

afterPUT (basket : Basket , billingAddress : OrderAddress ) : Status

The function is called after setting of the billing address to the basket.

Parameters:
basket - the basket based on which the order is created
billingAddress - the billing address that was set to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.billing_address.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket , addressRequest : OrderAddress ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
addressRequest - address request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v23_2/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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

Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "billing_address" : 
   {
      "_type" : "order_address",
      "city" : "Boston",
      "country_code" : "US",
      "first_name" : "John",
      "full_name" : "John Smith",
      "last_name" : "Smith",
      "c_strValue" : "cTest"
   },
...
}

# with an address from a customer profile
REQUEST:
PUT /dw/shop/v23_2/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address?customer_address_id=home HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "billing_address" : 
   {
      "_type" : "order_address",
      "city" : "Boston",
      "country_code" : "US",
      "first_name" : "John",
      "full_name" : "John Smith",
      "last_name" : "Smith",
      "c_strValue" : "cTest"
   },
...
}

Update basket with coupon

Adds a coupon to an existing basket.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/coupons

Formats

json, xml

Authentication

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

Request Document

CouponItem

Response Document

Basket

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
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
400 MissingCouponCodeException   Thrown if the coupon number is not provided.
400 InvalidCouponCodeException

couponCode (String)

 Thrown if the coupon code specified is invalid.
404 BasketNotFoundException

basketId (String)

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

beforePOST (basket : Basket , couponItem : CouponItem ) : Status

The function is called before adding a coupon to a basket.

Parameters:
basket - the basket the coupon get added to
couponItem - the coupon information
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.coupon.afterPOST

afterPOST (basket : Basket , couponItem : CouponItem ) : Status

The function is called after adding a coupon to a basket.

Parameters:
basket - the basket the coupon get added to
couponItem - the coupon information
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.coupon.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , couponRequest : CouponItem ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
couponRequest - coupon request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/bcRTDaOjgyscwaaadkrhhQHmrP/coupons HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
  "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidCouponItemException",
      "message" : "The coupon item with coupon code 'notExitingCoupon' is invalid."
   }
}

Remove coupon from basket

Removes a coupon from the basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/coupons/{coupon_item_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 CouponItemNotFoundException

couponItemId (String)

 Indicates 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.shop.basket.coupon.beforeDELETE

beforeDELETE (basket : Basket , couponItemID : String ) : Status

The function is called before removing a coupon from a basket.

Parameters:
basket - the basket the coupon get removed from
couponItemID - the coupon information
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.coupon.afterDELETE

afterDELETE (basket : Basket , couponItemID : String ) : Status

The function is called after removing a coupon from a basket.

Parameters:
basket - the basket the coupon get removed from
couponItemID - the coupon information
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.coupon.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , couponItemId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
couponItemId - coupon item id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v23_2/baskets/cgHV79aadbwZIaaaekLlYxEcg7/coupons/cd5ON9aacbJAQaaadlc1RUojQv HTTP/1.1
Host: example.com
Authorization:Bearer 2afa983a-3ece-441d-a6f4-cdb4af1cff56 
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Date:Thu, 19 Mar 2015 13:34:17 GMT
Server:Salesforce Commerce Cloud eCommerce Server/2.4.10 (Unix) OpenSSL/1.0.1f
Content-Length:2011
Keep-Alive:timeout=15, max=98
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "23.2",
   "fault" : 
   {
      "type" : "CouponItemNotFoundException",
      "message" : "The coupon item ID 'cd5ON9aacbJAQaaadlc1RUojQv' couldn't be found."
   }
}

Update customer of basket

Sets customer information for an existing basket.

Url

PUT https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/customer

Formats

json, xml

Authentication

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

Request Document

CustomerInfo

Response Document

Basket

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
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, 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 would be exceeded.
404 CustomerNotFoundException

customerId (String)

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

basketId (String)

 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.customer.beforePUT

beforePUT (basket : Basket , customerInfo : CustomerInfo ) : Status

The function is called before setting of customer information for the basket.

Parameters:
basket - the basket based on which the order is created
customerInfo - the customer information to be set to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.customer.afterPUT

afterPUT (basket : Basket , customerInfo : CustomerInfo ) : Status

The function is called after setting of customer information for the basket.

Parameters:
basket - the basket based on which the order is created
customerInfo - the customer information that were set to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.customer.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket , customerRequest : CustomerInfo ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
customerRequest - customer request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v23_2/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/customer HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
  "customer_no":"customer0012",
  "email":"[email protected]"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "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" : "23.2",
   "fault" : 
   {
      "type" : "CustomerNotFoundException",
      "message" : "No customer with ID 'customer0013' could be found."
   }
}

Add a gift certificate item to a basket

Adds a gift certificate item to an existing basket.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/gift_certificate_items

Formats

json, xml

Authentication

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

Request Document

GiftCertificateItem

Response Document

Basket

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
400 InvalidGiftCertificateItemAmountException

giftCertificateItemAmount (Decimal)

 Indicates that the gift certificate item amount is negative.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 ShipmentNotFoundException

shipmentId (String)

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

beforePOST (basket : Basket , item : GiftCertificateItem ) : Status

The function is called before adding a gift certificate item to a basket.

Parameters:
basket - the basket based on which the order is created
item - the gift certificate item to add
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.afterPOST

afterPOST (basket : Basket , item : GiftCertificateItem ) : Status

The function is called after adding a gift certificate item to a basket.

Parameters:
basket - the basket based on which the order is created
item - the gift certificate item to add
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , certificateItemRequest : GiftCertificateItem ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
certificateItemRequest - certificateItem request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Add a gift certificate item to a basket
#
REQUEST:
POST /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/gift_certificate_items HTTP/1.1
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
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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"
      }
   ],
...
}

Delete a gift certificate item from a basket

Deletes a gift certificate item from an existing basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}

Formats

json, xml

Authentication

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

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
basket_id String the id of the basket to be modified minLength=1
gift_certificate_item_id String the id of the gift certificate item to be removed minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 GiftCertificateItemNotFoundException

giftCertificateItemId (String)

 Indicates that the gift certificate item with the given gift certificate item id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.gift_certificate_item.beforeDELETE

beforeDELETE (basket : Basket , giftCertificateItemId : String ) : Status

The function is called before deleting a gift certificate item from a basket.

Parameters:
basket - the basket based on which the order is created
giftCertificateItemId - the id of the gift certificate item to be deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.afterDELETE

afterDELETE (basket : Basket , giftCertificateItemId : String ) : Status

The function is called after deleting a gift certificate item from a basket.

Parameters:
basket - the basket based on which the order is created
giftCertificateItemId - the id of the deleted gift certificate item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , giftCertificateItemId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
giftCertificateItemId - the id of the deleted gift certificate item
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Remove a gift certificate item from a basket
#
REQUEST:
DELETE /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/gift_certificate_items/915a3d54e1c18caed233c46153 HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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" : "23.2",
   "_type" : "basket",
   "_resource_state" : "5086203b16875cc1d545a634cabb76d297c18e098a41bff3a4420913f10fabae",
...
   "gift_certificate_line_items" : 
   [
      
      {
         "_type" : "gift_certificate_item",
         "amount" : 300.00,
         "gift_certificate_item_id" : "12343d54e1c18caed233c46153",
         "message" : "Present from your brother",
         "recipient_email" : "[email protected]", 
         "recipient_name" : "Jane Doe",
         "sender_name" : "John Doe",
         "shipment_id" : "beRyAiWcyEk4UaaadmbdFBKNcy"
      }
   ],
...
}

# in case of failure - basket for given ID is not found:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID 'cdcM6iWbN5jyIaaadh5thrJrYj' was found."
   }
}

Updates a gift certificate item of a basket

Updates a gift certificate item of an existing basket.

Url

PATCH https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}

Formats

json, xml

Authentication

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

Request Document

GiftCertificateItem

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
basket_id String the id of the basket to be modified minLength=1
gift_certificate_item_id String the id of the gift certificate item to be updated minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidGiftCertificateItemAmountException

giftCertificateItemAmount (Decimal)

 Indicates that the gift certificate item amount is negative.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 GiftCertificateItemNotFoundException

giftCertificateItemId (String)

 Indicates that the gift certificate item with the given gift certificate item id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.gift_certificate_item.beforePATCH

beforePATCH (basket : Basket , giftCertificateItemId : String , item : GiftCertificateItem ) : Status

The function is called before updating a gift certificate item of a basket.

Parameters:
basket - the basket based on which the order is created
giftCertificateItemId - the id of the gift certificate item to be updated
item - the new gift certificate item data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.afterPATCH

afterPATCH (basket : Basket , giftCertificateItemId : String , item : GiftCertificateItem ) : Status

The function is called after updating a gift certificate item of a basket.

Parameters:
basket - the basket based on which the order is created
giftCertificateItemId - the id of the updated gift certificate item
item - the new gift certificate item data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.gift_certificate_item.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket , giftCertificateItemId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
giftCertificateItemId - the id of the updated gift certificate item
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Update a gift certificate item of a basket
#
REQUEST:
PATCH /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/gift_certificate_items/915a3d54e1c18caed233c46153 HTTP/1.1
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" : 300.00 
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_type" : "basket",
   "_resource_state" : "5086203b16875cc1d545a634cabb76d297c18e098a41bff3a4420913f10fabae",
...
   "gift_certificate_line_items" : 
   [
      
      {
         "_type" : "gift_certificate_item",
         "amount" : 300.00,
         "gift_certificate_item_id" : "915a3d54e1c18caed233c46153",
         "message" : "Present from your brother",
         "recipient_email" : "[email protected]", 
         "recipient_name" : "Jane Doe",
         "sender_name" : "John Doe",
         "shipment_id" : "beRyAiWcyEk4UaaadmbdFBKNcy"
      }
   ],
...
}

# in case of failure - example when the basket does not contain gift certificate item with the provided id:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "giftCertificateItemId" : "915a3d54e1c18caed233c46153"
      },
      "type" : "GiftCertificateItemNotFoundException",
      "message" : "The gift certificate item with gift_certificate_item_id '915a3d54e1c18caed233c46153' was not found."
   }
}

Add items to a basket

Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are:
  • product_id: a valid product id. This is the id of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference.
  • shipment_id: a valid shipment id (optional). This is the id of the shipment in which the product item is created.
  • quantity: a number between 0.01 and 999. This is the quantity of the product to order.
  • inventory_id: a valid inventory id (optional). This is the id of the inventory from which the item is allocated.
  • bonus_discount_line_item_id: a valid bonus discount line item id (optional). This is the id of the bonus discount line item for which the added product is a selected bonus product.
  • option_items/option_value_id: a valid option value id. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the 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.
  • custom properties in the form c_<CUSTOM_NAME>: the custom property must correspond to a custom attribute (<CUSTOM_NAME>) defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/items

Formats

json, xml

Authentication

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

Request Document

ProductItem

Response Document

Basket

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
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 InvalidProductItemQuantityException   Indicates a null quantity value
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

 Indicates that the requested product quantity is not available.
400 InvalidProductTypeException

productId (String)

type (String)

 Indicates that the product cannot be added to the basket because of its type.
400 InvalidProductOptionItemException

productId (String)

optionId (String)

 Indicates that an option with the specified option id is unknown.
400 InvalidProductOptionValueItemException

productId (String)

optionValueId (String)

optionId (String)

 Indicates that an option with the specified option value id is unknown.
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, not relevant when using OAuth.
400 BonusDiscountLineItemNotFoundException

bonusDiscountLineItemId (String)

 Indicates that the provided bonus discount line item id is not present in the current basket.
400 BonusProductQuantityException

bonusDiscountLineItemId (String)

 Indicates that the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select.
400 InvalidBonusProductException

productId (String)

bonusDiscountLineItemId (String)

 Indicates that the selected bonus product is not an applicable product for the bonus discount line item provided.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 ShipmentNotFoundException

shipmentId (String)

 Indicates that the basket does not contain a shipment with the given shipment id.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.items.beforePOST

beforePOST (basket : Basket , items : ProductItem ) : Status

Parameters:
basket - the target basket
items - productItems array of product items
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.items.afterPOST

afterPOST (basket : Basket , items : ProductItem ) : Status

Parameters:
basket - the target basket
items - productItems array of product items
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.items.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , productItems : ProductItem ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
productItems - productItems array of product items
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/this/items HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "product_items" : [
      {
         "adjusted_tax" : 5.00,
         "base_price" : 16.49,
         "bonus_product_line_item" : false,
         "item_text" : "cup-white Product details...",
         "price" : 16.49,
         "price_after_item_discount" : 16.49,
         "price_after_order_discount" : 16.49,
         "product_id" : "cup-white",
         "product_name" : "cup-white Product Name",
         "quantity" : 1.0,
         "shipment_id" : "me",
         "tax" : 5.00,
         "tax_basis" : 16.49,
         "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidProductItemException",
      "message" : "Product 'cup-white' is unknown, offline or not assigned to the site catalog."
   }
}

Update an item of a basket

Updates an item in a basket. The following values in the request body are considered by the server:
  • 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/v23_2/baskets/{basket_id}/items/{item_id}

Formats

json, xml

Authentication

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

Request Document

ProductItem

Response Document

Basket

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidProductItemIdException

productItemId (String)

 Indicates that no product item with given item id was found for the basket.
400 InvalidProductItemException

productId (String)

 Indicates that the product with the given product id in the request body is invalid.
400 InvalidProductItemQuantityException   Indicates a null quantity value
400 InvalidProductOptionItemException

optionId (String)

 Indicates that an option with the specified option id is unknown.
400 InvalidProductOptionValueItemException

optionValueId (String)

optionId (String)

 Indicates that an option with the specified option value id is unknown.
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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown
404 ShipmentNotFoundException

shipmentId (String)

 Indicates that a shipment with it's given id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.item.beforePATCH

beforePATCH (basket : Basket , item : ProductItem ) : Status

The function is called before updating of the basket's item.

Parameters:
basket - the basket based on which the order is created
item - the product item delta containing the desired changes to the product item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.item.afterPATCH

afterPATCH (basket : Basket , item : ProductItem ) : Status

The function is called after updating of the basket's item.

Parameters:
basket - the basket based on which the order is created
item - the product item delta containing the desired changes to the product item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.item.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket , productItemId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
productItemId - productItemId request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Update option value
#
REQUEST:
PATCH /dw/shop/v23_2/baskets/cd6HwiWbLaZuUaaadgtglhMTrG/items/cdheYiWbLasNkaaadgwMthMTrG HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "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" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidOptionItemException",
      "message" : "Product option 'Insurance' is not supported."
   }
}

Remove product item from basket

Removes a product item from the basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/items/{item_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 ProductItemNotFoundException

itemId (String)

 Indicates that the product item with the given product item id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.item.beforeDELETE

beforeDELETE (basket : Basket , productItemId : String ) : Status

The function is called before a basket item is removed.

Parameters:
basket - the basket based on which the order is created
productItemId - the id of the product item to be removed
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.item.afterDELETE

afterDELETE (basket : Basket , productItemId : String ) : Status

The function is called after a basket item is removed.

Parameters:
basket - the basket based on which the order is created
productItemId - the id of the removed product item
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.item.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , productItemId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
productItemId - productItemId request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v23_2/baskets/ceK4aiWbN132MaaadkYERkclwC/items/cerZoiWbN1K2Yaaadk6URkclwC HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "product_items" : 
   [
      {
         "_type" : "product_item",
         "adjusted_tax" : 5.00,
         "base_price" : 16.49,
         "bonus_product_line_item" : false,
         "item_text" : "Simple Product",
         "price" : 16.49,
         "price_after_item_discount" : 16.49,
         "price_after_order_discount" : 16.49,
         "product_id" : "SimpleProduct",
         "product_name" : "Simple Product",
         "quantity" : 1.00,
         "shipment_id" : "me",
         "tax" : 5.00,
         "tax_basis" : 16.49,
         "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidCustomerException",
      "message" : "Invalid customer."
   }
}

# validation failure in case of an unknown product item id:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ProductItemNotFoundException",
      "message" : "The product item with ID '123' couldn't be found."
   }
}

Add a note to a basket

Adds a note to an existing basket.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/notes

Formats

json, xml

Authentication

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

Request Document

Note

Response Document

Basket

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 BasketNotFoundException

basketId (String)

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

beforePOST (basketId : String , note : Note ) : Status

The function is called before a note is added.

Parameters:
basketId - the basket
note - the note to be addded
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.note.afterPOST

afterPOST (basketId : String , note : Note ) : Status

The function is called after a note is added.

Parameters:
basket - the basket
note - the note to be added
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.note.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , noteRequest : Note ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
noteRequest - note request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Add a note to a basket
#
REQUEST:
POST /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/notes HTTP/1.1
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
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "notes" : { 
       "link" : "https://example.com/dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/notes"
    }
...
}

Get notes from a basket

Retrieves notes for a basket.

Url

GET https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/notes

Formats

json, xml

Authentication

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

Response Document

NotesResult

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 BasketNotFoundException

basketId (String)

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

beforeGET (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the basket id the notes result retrieved for.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.notes.modifyGETResponse_v2

modifyGETResponse_v2 (basket : Basket , notesResponse : NotesResult ) : Status

Parameters:
basket - the basket the notes result retrieved for.
notesResponse - notes response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/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" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "notes_result",
   "notes" : 
   [
      {
         "subject" : "Unhappy customer",
         "text" : "The customer was not very happy due to a delay."
      },
      {
         "subject" : "Happy customer",
         "text" : "The customer is already happy!"
      }
   ]
}

Remove a note from a basket

Removes a basket note.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/notes/{note_id}

Formats

json, xml

Authentication

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

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
basket_id String the id of the basket to be modified minLength=1
note_id String the id of the note to be removed minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 BasketNotFoundException

basketId (String)

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

beforeDELETE (basket : Basket , note : Note ) : Status

The function is called before a note is deleted.

Parameters:
basket - the basket
note - the note to be removed
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.note.afterDELETE

afterDELETE (basket : Basket , note : Note ) : Status

The function is called after a note is deleted.

Parameters:
basket - the basket
note - the note to be removed
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.note.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , noteId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
noteId - deleted note id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v23_2/baskets/00000029/notes/cdXTraOu6bXT6aaadll5tOJvce HTTP/1.1
Host: example.com
Authorization:Bearer 80a68fc6-945c-49e2-bfd6-abc9994de307
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "notes" : 
   {
      "_type" : "simple_link",
      "link" : "https://example.com/dw/shop/v23_2/baskets/bc0KwiWexX0ZQaaadqRTwMZFga/notes"
   },
...
}


# in case of validation failure - example response when the note to be deleted can not be found:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "NoteNotFoundException",
      "message" : "The note 'NonExisting' could not be found."
   }
}

Add payment instrument to basket

Adds a payment instrument to a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See POST /orders/{order_no}/payment_instruments and PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}. NOTE: If CREDIT_CARD is selected as the payment_method_id, it is mandatory to provide the property card_type.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/payment_instruments

Formats

json, xml

Authentication

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

Request Document

BasketPaymentInstrumentRequest

Response Document

Basket

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 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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

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

beforePOST (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called before payment instrument adding to a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be added to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.afterPOST

afterPOST (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called after payment instrument adding to a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument added to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , paymentInstrumentRequest : BasketPaymentInstrumentRequest ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
paymentInstrumentRequest - payment instrument request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/cgUZoiWbN19xdaaaekBrRkclwC/payment_instruments HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 1.00,
         "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidPaymentMethodIdException",
      "message" : "The payment method with ID 'InvalidPaymentMethodId' cannot be applied."
   }
}

Updates payment instrument of basket

Updates a payment instrument of a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See POST /orders/{order_no}/payment_instruments and PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}

Url

PATCH https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

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

Request Document

BasketPaymentInstrumentRequest

Response Document

Basket

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

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. Please see dw.order.PaymentInstrument.isPermanentlyMasked() for detailed information.
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

 Indicates that 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.payment_instrument.beforePATCH

beforePATCH (basket : Basket , paymentInstrument : OrderPaymentInstrument , newPaymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called before updating a payment instrument of a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be updated
newPaymentInstrument - the new payment instrument data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.afterPATCH

afterPATCH (basket : Basket , paymentInstrument : OrderPaymentInstrument , paymentInstrumentRequest : BasketPaymentInstrumentRequest ) : Status

The function is called after updating a payment instrument of a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the updated payment instrument
paymentInstrumentRequest - the new payment instrument data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket , paymentInstrumentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
paymentInstrumentRequest - payment instrument id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v23_2/baskets/cg2N2iWbN1ApAaaaekYdekclwC/payment_instruments/cgqoaiWbN1fhsaaaek6dekclwC HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "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" : "23.2",
   "fault" : 
   {
      "type" : "PaymentInstrumentPermanentlyMaskedException",
      "message" : "The payment instrument with ID 'ceqRMiWbN1my2aaadkgYlkclwC' already permanently masked."
   }
}

Removes a payment instrument from a basket

Removes a payment instrument of a basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

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

beforeDELETE (basket : Basket , delete : OrderPaymentInstrument ) : Status

It is called before the order payment instrument is removed from the basket.

Parameters:
basket - the basket to remove the payment instrument from
delete - the order payment instrument document.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.afterDELETE

afterDELETE (basket : Basket ) : Status

It is called after the order payment instrument is removed from the basket.

Parameters:
basket - the basket the payment instrument was removed from
paymentInstrument - the payment instrument to be deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_instrument.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , paymentInstrumentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
paymentInstrumentRequest - payment instrument id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

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

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "payment_instruments" : 
   [
      
      {
        ...
      }
   ],
...
}

# validation failure in case of an unknown payment instrument id:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "PaymentInstrumentNotFoundException",
      "message" : "The payment instrument with payment_instrument_id '123' couldn't be found."
   }
}

Get applicable payment methods for basket

Gets applicable payment methods for an existing basket considering the open payment amount only.

Url

GET https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/payment_methods

Formats

json, xml

Authentication

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

Response Document

PaymentMethodResult

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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

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

beforeGET (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the basket id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_methods.afterGET

afterGET (basket : Basket , paymentMethods : PaymentMethodResult ) : Status

Called before returning the list of available payment methods to the customer. Allowing modifications of the result.

Parameters:
basket - the basket
paymentMethods - the available payment methods
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.payment_methods.modifyGETResponse_v2

modifyGETResponse_v2 (basket : Basket , paymentMethodResultResponse : PaymentMethodResult ) : Status

Parameters:
basket - the basket the payment method result retrieved for.
paymentMethodResultResponse - paymentMethodResult response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/payment_methods HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19

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" : "23.2",
   "_type" : "payment_method_result",
   "applicable_payment_methods" : 
   [
      {
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "_type" : "payment_method",
         "id" : "BANK_TRANSFER",
         "name" : "Bank Transfer"
      },
      
      {
         "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "_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" : "Mastercard",
               "number_lengths" : 
               [
                  "16"
               ],
               "number_prefixes" : 
               [
                  "2221-2720",
                  "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"
      },
      {
         "_resource_state" : 9cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "_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)"
      },
      {
         "_resource_state" : "cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "_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)"
      },
      {
         "_resource_state" : "41470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "_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" : "23.2",
   "fault" : 
   {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID 'non_existing_basket' could be found."
   }
}

Add price adjustment to basket

Adds a custom manual price adjustment to the basket.

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/price_adjustments

Formats

json, xml

Authentication

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

Request Document

PriceAdjustmentRequest

Response Document

Basket

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
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.
400 PriceAdjustmentLimitExceededException

priceAdjustmentLimit (Decimal)

 Indicates that the price adjustment limit is exceeded.
404 BasketNotFoundException

basketId (String)

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

beforePOST (basket : Basket , request : PriceAdjustmentRequest ) : Status

The function is called before a custom price adjustment is added.

Parameters:
basket - the basket
request - The request for the price adjustment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.afterPOST

afterPOST (basket : Basket , request : PriceAdjustmentRequest ) : Status

The function is called after a custom price adjustment was added.

Parameters:
basket - the basket
request - The request for the price adjustment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , priceAdjustmentRequest : PriceAdjustmentRequest ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
priceAdjustmentRequest - price adjustment request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/cdpcIiWbO5cMcaaadlIDUtofOK/price_adjustments HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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" : "23.2",
   "fault" : 
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'POST /dw/shop/v23_2/baskets' is not allowed for current user."
   }
}

Remove price adjustment from basket

Removes a custom manual price adjustment from the basket.

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/price_adjustments/{price_adjustment_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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

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 BasketNotFoundException

basketId (String)

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

beforeDELETE (basket : Basket , priceAdjustmentId : String ) : Status

The function is called before a custom price adjustment is removed.

Parameters:
basket - the basket
priceAdjustmentId - the id of the price adjustment to be deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.afterDELETE

afterDELETE (basket : Basket , priceAdjustmentId : String ) : Status

The function is called after a custom price adjustment was removed.

Parameters:
basket - the basket
priceAdjustmentId - the id of the deleted price adjustment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , priceAdjustmentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
priceAdjustmentId - price adjustment id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v23_2/baskets/cdpcIiWbO5cMcaaadlIDUtofOK/price_adjustments/cd0PQiWbO5xrQaaadllDYtofOK HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json;charset=UTF-8
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# in case of success when a product item price adjustment is deleted:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...   
   "product_items" : 
   [
      {
         "_type" : "product_item",
         "adjusted_tax" : 10.00,
         "base_price" : 16.49,
         "bonus_product_line_item" : false,
         "item_text" : "Simple Product",
         "price" : 116.48,
         "price_after_item_discount" : 116.48,
         "price_after_order_discount" : 116.48,
         "product_id" : "SimpleProduct",
         "product_name" : "Simple Product",
         "quantity" : 2.00,
         "shipment_id" : "me",
         "tax" : 10.00,
         "tax_basis" : 116.48,
         "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" : "23.2",
   "fault" : 
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /dw/shop/v23_2/baskets' is not allowed for current user."
   }
}

Updates a price adjustment on a basket

Updates a custom manual price adjustment on the basket. Only the following PATH values are considered for the update: discount, item_text, reason_code and custom properties; all other attributes are ignored. The discount type of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type PERCENTAGE, the 'percentage' attribute is mandatory. For adjustments of type AMOUNT and FIXED_PRICE, the 'amount' attribute is mandatory.

Url

PATCH https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/price_adjustments/{price_adjustment_id}

Formats

json, xml

Authentication

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

Request Document

PriceAdjustment

Response Document

Basket

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 PriceAdjustmentUpdateNotManualException

priceAdjustmentId (String)

 Indicates that the price adjustment is not manual and cannot be updated.
400 PriceAdjustmentUpdateAttributeMissingException

attribute (String)

discountType (String)

 Indicates that the expected attributes are missing in the input.
400 PriceAdjustmentUpdateTypeMismatchException

existingDiscountType (String)

inputDiscountType (String)

 Indicates that the type of a price adjustment does not match the adjustment type of the input data.
400 PriceAdjustmentLimitExceededException

priceAdjustmentLimit (Decimal)

 Indicates that the price adjustment limit is exceeded.
404 PriceAdjustmentIdNotFoundException

priceAdjustmentId (String)

 Indicates that the priceAdjustmentId is not found.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.basket.price_adjustment.beforePATCH

beforePATCH (basket : Basket , priceAdjustmentId : String , priceAdjustmentWO : PriceAdjustment ) : Status

The function is called before a custom price adjustment is updated.

Parameters:
basket - the basket
priceAdjustmentId - the id of the price adjustment to be updated
priceAdjustmentWO - the new price adjustment data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.afterPATCH

afterPATCH (basket : Basket , priceAdjustmentId : String , priceAdjustmentWO : PriceAdjustment ) : Status

The function is called after a custom price adjustment was updated.

Parameters:
basket - the basket
priceAdjustmentId - the id of the updated price adjustment
priceAdjustmentWO - the new price adjustment data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.price_adjustment.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket , priceAdjustmentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
priceAdjustmentId - price adjustment id
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v23_2/baskets/b30bdba5b8ed654e6e236e2ff3/price_adjustments/e397cd21f9a9c0643277ba1011 HTTP/1.1
Host: example.com
Authorization: Bearer cd669706-3638-4dd1-a8b2-310ab900ca53
Content-Type: application/json;charset=UTF-8
{
  "applied_discount" : {
                 "amount" : 15,
                 "type" : "amount"
               },
  "item_text" : "MyOrderAdjustment",
  "reason_code" : "override manual promo"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "basket",
...
   "order_price_adjustments" : 
   [
      
      {
         "_type" : "price_adjustment",
         "applied_discount" : 
         {
            "_type" : "discount",
            "amount" : 15,
            "type" : "amount"
         },
         "created_by" : "testWapiAgent",
         "creation_date" : "2017-03-14T09:15:35.543Z",
         "custom" : true,
         "item_text" : "MyOrderAdjustment",
         "last_modified" : "2017-03-14T09:15:35.594Z",
         "manual" : true,
         "price" : -15.00,
         "price_adjustment_id" : "e397cd21f9a9c0643277ba1011",
         "promotion_id" : "manual adjustment",
         "reason_code" : "override manual promo",
         "uuid" : "e397cd21f9a9c0643277ba1011",
         "c_wapi-string" : "my custom property"
      }
   ],
...
}

# in case of validation failure - example response in case required attributes are missing in the input:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "attribute" : "percentage",
         "discountType" : "PERCENTAGE"
      },
      "type" : "PriceAdjustmentUpdateAttributeMissingException",
      "message" : "Expected attribute 'percentage' not found for price adjustment of type 'PERCENTAGE'."
   }
}

Create shipment for a basket

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:
  • the id
  • the shipping address
  • the shipping method
  • gift boolean flag
  • gift message
  • custom properties

Url

POST https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/shipments

Formats

json, xml

Authentication

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

Request Document

Shipment

Response Document

Basket

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
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 InvalidShippingMethodIdException

shippingMethodId (String)

 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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

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

beforePOST (basket : Basket , shipment : Shipment ) : Status

The function is called before the creation of a shipment for a basket.

Parameters:
basket - the basket based on which the shipment will be created
shipment - the shipment information for the shipment creation
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.afterPOST

afterPOST (basket : Basket , shipment : Shipment ) : Status

The function is called after the creation of a shipment for a basket.

Parameters:
basket - the basket based on which the shipment was created
shipment - the shipment information for the shipment creation
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.modifyPOSTResponse

modifyPOSTResponse (basket : Basket , basketResponse : Basket , shipmentRequest : Shipment ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
shipmentRequest - shipment request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Create a shipment for a basket
#
REQUEST:
POST /dw/shop/v23_2/baskets/cdcM6iWbN5jyIaaadh5thrJrYj/shipments HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "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" : "23.2",
  "fault": {
    "details": {
      "validation.type": "InvalidShippingMethod",
      "validation.message": "The shipping method with ID 'NotExistingMethodId' is unknown or cannot be applied to the basket."
    },
    "type": "InvalidShippingMethodIdException",
    "message": "The shipping method with ID 'NotExistingMethodId' is unknown or cannot be applied to the basket."
  }
}

Update shipment for a basket

Updates a shipment for a basket. The body can include updated values for the following properties:
  • the id
  • the shipping address
  • the shipping method
  • gift boolean flag
  • gift message
  • custom properties

Url

PATCH https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/shipments/{shipment_id}

Formats

json, xml

Authentication

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

Request Document

Shipment

Response Document

Basket

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

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

shipmentNo (String)

 Indicates that a shipment with the provided shipment number already exists for the basket.
400 MissingShippingMethodIdException

shipmentId (String)

 Indicates a missing shipping method.
400 InvalidShippingMethodIdException

shippingMethodId (String)

 Indicates an invalid shipping method.
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

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

beforePATCH (basket : Basket , shipment : Shipment , shipmentInfo : Shipment ) : Status

The function is called before changing of a shipment for a basket.

Parameters:
basket - the basket based on which the shipment will be updated
shipment - the current shipment to be updated
shipmentInfo - the shipment information for the shipment update (update data)
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.afterPATCH

afterPATCH (basket : Basket , shipment : Shipment , shipmentInfo : Shipment ) : Status

The function is called after patching of a shipment for a basket.

Parameters:
basket - the basket based on which the shipment was changed
shipment - the shipment which has been updated
shipmentInfo - the shipment information for the shipment update
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.modifyPATCHResponse

modifyPATCHResponse (basket : Basket , basketResponse : Basket , shipmentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
shipmentId - shipment id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Update a shipment of a basket
#
REQUEST:
PATCH /dw/shop/v23_2/baskets/cdHyF9aacbudgaaadl5x7bVp1i/shipments/cdL6b9aacbUNAaaadlbiBbVp1i HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
    "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
    "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:Salesforce Commerce Cloud eCommerce Server/2.4.10 (Unix) OpenSSL/1.0.1f
Content-Length:2815

Keep-Alive:timeout=15, max=97
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "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" : "23.2",
  "fault": {
    "details": {
      "validation.type": "InvalidShippingMethod",
      "validation.message": "The shipping method with ID 'NotExistingMethodId' is unknown or cannot be applied to the basket."
    },
    "type": "InvalidShippingMethodIdException",
    "message": "The shipping method with ID 'NotExistingMethodId' is unknown or cannot be applied to the basket."
  }
}

Remove shipment from basket

Removes a specified shipment and all associated product, gift certificate, shipping and price adjustment line items from a basket. You can't remove a default shipment (id = "me").

Url

DELETE https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/shipments/{shipment_id}

Formats

json, xml

Authentication

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

Response Document

Basket

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 deleted 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, not relevant when using OAuth.
403 DefaultShipmentDeletionForbiddenException

shipmentId (String)

 Indicates that the given shipment id corresponds to the default shipment (shipment ID always set to "me") and cannot be removed.
404 BasketNotFoundException

basketId (String)

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

beforeDELETE (basket : Basket , shipment : Shipment ) : Status

Called before the basket's shipment is removed.

Parameters:
basket - the basket to be updated
shipment - the shipment to be deleted
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.afterDELETE

afterDELETE (basket : Basket , shipmentId : String ) : Status

Called after the basket's shipment was removed.

Parameters:
basket - the basket which was updated
shipmentId - the id of the deleted shipment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.modifyDELETEResponse

modifyDELETEResponse (basket : Basket , basketResponse : Basket , shipmentId : String ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
shipmentId - shipment id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

#
# Example: Delete a shipment from a basket
#
REQUEST:
DELETE /dw/shop/v23_2/baskets/cdHyF9aacbudgaaadl5x7bVp1i/shipments/cdL6b9aacbUNAaaadlbiBbVp1i HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
x-dw-resource-state: 847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb

# in case of success:

RESPONSE:
HTTP/1.1 200 OK

Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "shipments": [
    {
      "gift":false,
      "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": "abc6b9aacbUNAaaadlbiBbVp1i",
      "c_somestring" : "shipment_custom_property"
    }
  ],
...
}

# in case of validation failure - example response when the shipment ID corresponds to the default basket shipment:
RESPONSE:
HTTP/1.1 403 FORBIDDEN
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "shipmentId" : "me"
      },
      "type" : "DefaultShipmentDeletionForbiddenException",
      "message" : "The shipment with ID 'me' corresponds to the default shipment and cannot be deleted."
   }
}

Sets the shipping address of a shipment

Sets a shipping address of a specific shipment of a basket.

Url

PUT https://hostname:port/dw/shop/v23_2/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.
OAuth Authentication via OAuth token. A valid user is required.

Request Document

OrderAddress

Response Document

Basket

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.  

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 (not relevant when using OAuth).
400 InvalidCustomerException   Indicates that an customerAddressId was provided but either an anonymous or no customer was set.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 AddressNotFoundException

addressName (String)

 Indicates 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.shipment.shipping_address.beforePUT

beforePUT (basket : Basket , shipment : Shipment , shippingAddress : OrderAddress ) : Status

The function is called before setting of the shipping address to a certain shipment of the basket.

Parameters:
basket - the basket based on which the order is created
shipment - the shipment information for the shipment creation
shippingAddress - the shipping address to be set to the shipment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.shipping_address.afterPUT

afterPUT (basket : Basket , shipment : Shipment , shippingAddress : OrderAddress ) : Status

The function is called after setting of the shipping address to a certain shipment of the basket.

Parameters:
basket - the basket based on which the order is created
shipment - the shipment information for the shipment creation
shippingAddress - the shipping address that was set to the shipment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.shipping_address.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket , orderAddressRequest : OrderAddress ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
orderAddressRequest - order address request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v23_2/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/shipments/shipmentId123/shipping_address HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "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"
      }
   ],
...
}

REQUEST:
PUT /dw/shop/v23_2/baskets/cdCxIiWbPdiKAaaadhKTtczLvk/shipments/shipmentId123/shipping_address?customer_address_id=homeaddress HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
}

# in case of success:

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

Set shipping method to shipment

Sets a shipping method to a specific shipment of a basket.

Url

PUT https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/shipments/{shipment_id}/shipping_method

Formats

json, xml

Authentication

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

Request Document

ShippingMethod

Response Document

Basket

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MissingShippingMethodIdException

shipmentId (String)

 Indicates that the id of the shipping method is missing.
400 InvalidShippingMethodIdException

shippingMethodId (String)

 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, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 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.shipment.shipping_method.beforePUT

beforePUT (basket : Basket , shipment : Shipment , shippingMethod : ShippingMethod ) : Status

The function is called before setting of the shipping method to a certain shipment of the basket.

Parameters:
basket - the basket based on which the order is created
shipment - the shipment information for the shipment creation
shippingMethod - the shipping method to be set to the shipment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.shipping_method.afterPUT

afterPUT (basket : Basket , shipment : Shipment , shippingMethod : ShippingMethod ) : Status

The function is called after setting of the shipping method to a certain shipment of the basket.

Parameters:
basket - the basket based on which the order is created
shipment - the shipment information for the shipment creation
shippingMethod - the shipping method that was set to the shipment
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipment.shipping_method.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket , shippingMethodRequest : ShippingMethod ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
shippingMethodRequest - shipping method request object
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.validateBasket

validateBasket (basketResponse : Basket , duringSubmit : boolean ) : Status

Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter duringSubmit indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.

Example showing addition, listing and removal of flashes: 


 exports.validateBasket = function( basketResponse, duringSubmit ) {
     basketResponse.addFlash( {
         type: "MyType",
         message: "My message",
         path: "my_path",
         details: { "k1": "v1", "k2": "v2" }
     } );
     var flashToRemove;
     for each( f in basketResponse.flashes ) {
         if ( f.type == "SomeOtherType" ) {
             flashToRemove = f;
         }
     }
     if ( flashToRemove != null ) {
         basketResponse.removeFlash( flashToRemove );
     }
 };
Parameters:
basketResponse - the basket response to be validated, before any OCAPI property selection is applied
duringSubmit - should the basket be checked for submit
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v23_2/baskets/cdqwkiWbPdFlkaaadh8xRczLvx/shipments/shipmentId1/shipping_method HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
  "id":"BaseShippingMethod"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...   
   "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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidShippingMethodIdException",
      "message" : "The shipping method with ID 'BaseShippingMethod2' is unknown or cannot be applied to the basket."
      ...
   }
}

Get applicable shipping methods for certain shipment of basket

Gets the applicable shipping methods for a certain shipment of a basket.

Url

GET https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/shipments/{shipment_id}/shipping_methods

Formats

json, xml

Authentication

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

Response Document

ShippingMethodResult

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 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

 Indicates that the basket with the given basket id is unknown.
404 ShipmentNotFoundException

shipmentId (String)

 Indicates 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.shipments.shipping_methods.beforeGET

beforeGET (basketId : String , shipmentId : String ) : Status

The function is called before the request will be processed.

Parameters:
basketId - the target basket id
shipmentId - the shipment id
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.shipments.shipping_methods.modifyGETResponse_v2

modifyGETResponse_v2 (shipment : Shipment , shippingMethodResult : ShippingMethodResult ) : Status

Parameters:
shipment - the shipment the shipping methods result retrieved for.
shippingMethodResult - shipping method result object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/baskets/this/shipments/me/shipping_methods HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
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" : "23.2",
   "_type" : "shipping_method_result",
   "applicable_shipping_methods" : 
   [
      {
         "_type" : "shipping_method",
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "description" : "The default shipping method.",
         "id" : "DefaultShippingMethod",
         "name" : "Default Shipping Method",
         "price" : 5.55
      },
      {
         "_type" : "shipping_method",
         "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "description" : "The base shipping method.",
         "id" : "BaseShippingMethod",
         "name" : "Base Shipping Method",
         "price" : 0.99
      },
      {
         "_type" : "shipping_method",
         "_resource_state" : "c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "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" : "23.2",
   "fault" : 
   {
      "type" : "ShipmentNotFoundException",
      "message" : "No shipment with ID 'non-existingShipmentId' could be found."
   }
}

Put a basket as storefront basket.

Marks a basket as storefront basket.

Url

PUT https://hostname:port/dw/shop/v23_2/baskets/{basket_id}/storefront?exchange={Boolean}

Formats

json, xml

Authentication

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

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
basket_id String the basket id minLength=1

Query Parameters

Parameter Type Description Constraints
exchange Boolean if true an existing storefront basket will be exchanged and marked as agent basket. if false a CustomerBasketsQuotaExceededException will be thrown.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CustomerBasketsQuotaExceededException

basketIds (String)

 Thrown if a storefront basket already exists and exchange is false.
404 BasketNotFoundException

basketId (String)

 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.storefront.beforePUT

beforePUT (basketId : String ) : Status

The function is called before the request will be processed.

Parameters:
basket - the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.storefront.afterPUT

afterPUT (basket : Basket ) : Status

The function is called after a put of a basket as storefront basket.

Parameters:
basket - the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.basket.storefront.modifyPUTResponse

modifyPUTResponse (basket : Basket , basketResponse : Basket ) : Status

Parameters:
basket - the target basket
basketResponse - basket response object
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v23_2/baskets/123324d33edew2443/storefront HTTP/1.1
Host: example.com
Authorization: Bearer xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Content-Type: application/json


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
  "basket_id" : "bcRTDaOjgyscwaaadkrhhQHmrP",
  "agent_basket": false,
...
}

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

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