Basket Resource (Shop API 15.1)

Summary

Http Method Resource Description
GET /Basket/{Id} Returns a limited set of basket information. Limited means that no checkout related information (i.e. addresses, shipping and payment method) are returned. This resource is typically used to implement a mini basket.
PATCH /Basket/{Id} Updates the basket using a basket delta document that you provide. This document describes changes made to the basket since the server last stored the basket's state. When you update a basket, keep the following considerations in mind:
  • Each PATCH request must include the If-Match header, which holds the last known base-point information - an ETag representing the current basket state on the server. You can obtain this ETag by calling "Get Basket", "Add Product to Basket," or "Update Basket."
    • If the request omits the If-Match header with the current server basket ETag , the server returns a 409 (Conflict) fault.
    • If the If-Match header does not match the current server basket ETag , the server returns a 412 (Precondition Failed) fault.
  • Server items are identified by the position of the document item in the item array.
  • Server items related to empty delta document items are not touched.
  • Delta items not represented on the server result in the creation of new items at the end of the items array. The merchant product item creation rules (merge items, and so on) do not apply.
  • Delta basket information is updated atomically (written completely or not written at all).
  • Basket is always recalculated in context of an update.
POST /Basket/{Id}/Add Adds a product (in a specified quantity) to the basket. In case of complex products, like a bundle with master bundled products, the default variants and options are used. Optionally an inventory_id can be provided, that defines the inventory list in which the product should be reserved and decremented. Only the properties product_id, quantity and inventory_id from the incoming productItemWO are evaluated. All other incoming product item properties are ignored.
GET /Basket/{Id}/Checkout Returns the complete set of basket information, including address and shipping information.
POST /Basket/{Id}/Checkout/Payment_instruments Creates a new payment instrument for the basket. This payment instrument must define a payment method. The current basket is retrieved.
DELETE /Basket/{Id}/Checkout/Payment_instruments/{Uuid} Deletes a payment instrument with the uuid from the URL from the basket. The current basket is retrieved.
PATCH /Basket/{Id}/Checkout/Payment_instruments/{Uuid} Updates a payment instrument with the uuid from the URL in the current basket. The current basket is retrieved.
GET /Basket/{Id}/Checkout/Payment_methods Returns a result object containing up to 100 applicable payment methods for the billing address and checkout amount.
POST /Basket/{Id}/Checkout/Set_billing_address Sets the billing address to basket. Any address validation errors result in a 400 fault message.
POST /Basket/{Id}/Checkout/Set_customer_info Sets the customer information for the basket. Any customer email validation errors result in a 400 fault message.
POST /Basket/{Id}/Checkout/Set_shipping_address Sets the shipping address to baskets default shipment.
POST /Basket/{Id}/Checkout/Set_shipping_method Sets the shipping method for the basket's default shipment. If the shipping method is unknown or disabled, this action returns a 400 fault. If the shipping method is not applicable to all items in the basket, this action returns a 400 fault. If the shipping method is not applicable for the shipping address, this action returns a 400 fault. If the shipping method is restricted to certain address and no shipping address is defined, this action returns a 400 fault. Otherwise, this action sets the shipping method.
GET /Basket/{Id}/Checkout/Shipping_methods Returns a result object containing up to 100 applicable shipping methods for the default shipment shipping address and product items.
POST /Basket/{Id}/Checkout/Submit Creates an order with status CREATED out of the basket. The order is not yet placed. This action returns a 400 fault in case any basket or checkout information are missing or invalid.

Get Basket

Returns a limited set of basket information. Limited means that no checkout related information (i.e. addresses, shipping and payment method) are returned. This resource is typically used to implement a mini basket.

Url

GET http://hostname:port/dw/shop/v15_1/basket/{id}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The id of the requested basket. Only 'this' is allowed.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Sample

REQUEST:
GET /dw/shop/v15_1/basket/this 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
ETag: 1d4558a9fdaee4679a0c1ba962b246865b0a32d12f0aa98d007b4cf4d2988c82
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 96.00,
  "product_total" : 86.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" : 
  [
    {
      "product_id" : "123",
      "item_text" : "Product foo",
      "quantity" : 2.00,
      "product_name" : "foo",
      "base_price" : 30.00,
      "price" : 60.00
    },
    {
      "product_id" : "456",
      "item_text" : "Product foo",
      "quantity" : 1.00,
      "product_name" : "bar",
      "base_price" : 40.00,
      "price" : 40.00,
      "price_adjustments" : 
      [
        {
          "promotion_id" : "10% off",
          "promotion_link" : "http://example.com/dw/shop/v146/promotions/10_percent_off",
          "item_text" : "10% off",
          "price" : -4.00
        }
      ]
    }
  ],
  "order_price_adjustments" : 
  [
    {
      "promotion_id" : "10$ off",
      "promotion_link" : "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
      "item_text" : "10$ off",
      "price" : -10.00
    }
  ]
}

Update Basket

Updates the basket using a basket delta document that you provide. This document describes changes made to the basket since the server last stored the basket's state. When you update a basket, keep the following considerations in mind:

Url

PATCH http://hostname:port/dw/shop/v15_1/basket/{id}

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

Basket

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String the basket id  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidMessageException   Thrown if the request body is malformed, the product_id length is larger than 100 characters, or if the quantity exceeds the range (0.01-999.00).
400 InvalidOptionItemException   Thrown if option_id or option_value_id is unknown.
400 InvalidProductItemException

productId (String)

Thrown if product_id is unknown, the product type is not supported (Master, Set), or no price is available.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown if the product_item is not available.
400 InvalidCouponItemException

couponCode (String)

Thrown if a given coupon code is invalid.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown in case a product is not available anymore.
404 NotFoundException   Thrown if a basket was requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterUpdate (basket : Basket , update : Basket ) : Status

It is called after the basket was updated with update document.

Parameters:
basket - the updated basket, must be (re)calculated.
update - the update document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeUpdate

beforeUpdate (basket : Basket , update : Basket ) : Status

It is called before the basket is updated with update document.

Parameters:
basket - the basket to update.
update - the update document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

#
# Example 1: Update product items
#
REQUEST:
PATCH /dw/shop/v15_1/basket/this HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==
If-Match: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
  "product_items" : 
  [
    { 
      "_at" : 1,                  // update product item with index 1 (the second one) in the array
      "product_id" : "999"        // replace the item product
    },     
    {
      "_at" : 2,                  // update product item with index 2 (the third one) in the array
      "quantity" : 2.00           // update item quantity
    },
    {
      "_delete_at" : 3            // delete product item with index 3 (the fourth one)      
    }
  ]
}

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

{
  "_v" : "15.1",
  "_flash" :
  [
    {
      "type" : "ProductItemNotAvailable",
      "path" : "$.product_items[0]"
    }
  ],
  "currency" : "USD",
  "product_sub_total" : 200.00,
  "product_total" : 200.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" :
  [
    {
      "product_id" : "007",
      "item_text" : "Product PS3",
      "quantity" : 1.00,
      "product_name" : "PS3",
      "base_price" : 100.00,
      "price" : 100.00
    },
    {
      "product_id" : "999",
      "item_text" : "Product acb",
      "quantity" : 2.00,
      "product_name" : "abc",
      "base_price" : 10.00,
      "price" : 20.00
    },
    {
      "product_id" : "456",
      "item_text" : "Product bar",
      "quantity" : 2.00,
      "product_name" : "bar",
      "base_price" : 40.00,
      "price" : 80.00
    }
  ]
}


#
# Example 2: Update variant selection of a bundled product item
#
REQUEST:
PATCH /dw/shop/v15_1/basket/this HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==; 
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp
{
  "product_items" : 
  [
    {
      "_at" : 0,                        // update product item with index 0 (the first one) in the array
      "bundled_product_items" :
      [
        {
          "_at" : 0,                    // update bundle product item with index 0 (the first one) in the array
          "product_id" : "RedSock"      // select another variant to be used for second bundled product item
        }
      ]
    }
  ]
}

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 240.00,
  "product_total" : 240.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" : 
  [
    {
      "product_id" : "CrazyRunningBundle",
      "item_text" : "Product Crazy Running Bundle",
      "quantity" : 1.00,
      "product_name" : "Crazy Running Bundle",
      "base_price" : 120.00,
      "price" : 120.00,
      "bundled_product_items" : 
      [
        {
          "product_id" : "ExtraordinaryBoots",
          "item_text" : "Product Extraordinary Boots",
          "quantity" : 1.00,
          "product_name" : "Extraordinary Boots"
        },
        {
          "product_id" : "RedSocks",
          "item_text" : "Product Red Socks",
          "quantity" : 1.00,
          "product_name" : "Red Socks"
        }
      ]
    }
  ]
}


#
# Example 3: Update option selection of an option item
#
REQUEST:
PATCH /dw/shop/v15_1/basket/this HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==; 
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp

{
  "product_items" : 
  [
    {
      "_at" : 0,                        // update product item with index 0 (the first one) in the array
      "option_items" :
      [
        {
          "_at" : 0,                    // update option item with index 0 (the first one) in the array    
          "option_value_id" : "512gb",  // explicitly configure another option value to be used
        }
      ]
    }
  ]
}

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 240.00,
  "product_total" : 240.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" :
  [
    {
      "product_id" : "PC",
      "item_text" : "Product PC",
      "quantity" : 1.00,
      "product_name" : "PC",
      "base_price" : 299.00,
      "price" : 299.00,
      "option_items" : 
      [
        {
          "option_id" : "hdd",            
          "option_value_id" : "512gb",     // explicitly configured via request
          "item_text" : "512GB HDD",
          "quantity" : 1.00,
          "base_price" : 100.00,
          "price" : 100.00
        },
        {
          "option_id" : "cpu",
          "option_value_id" : "dualcore",  // implicitly configured - default option
          "item_text" : "Dual Core",
          "quantity" : 1.00,
          "base_price" : 199.00,
          "price" : 199.00
        }
      ]
    }
  ]
}


#
# Example 4: Update coupon items
#
REQUEST:
PATCH /dw/shop/v15_1/basket/this HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==
If-Match: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
  "coupon_items" : 
  [
    {
      "_delete_at" : 0              // delete coupon item with index 0 (the first one)      
    },
    {
      "code" : "SUMMER2011"         // add new coupon item at the end of the coupon item array
    }
  ]
}

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

{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 200.00,
  "product_total" : 200.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" : [{ ... }],
  "coupon_items" : 
  [
    {
      "code" : "SUMMER2011",
      "status_code" : "applied",
      "valid" : true
    }
  ]
}

Add Product to Basket

Adds a product (in a specified quantity) to the basket. In case of complex products, like a bundle with master bundled products, the default variants and options are used. Optionally an inventory_id can be provided, that defines the inventory list in which the product should be reserved and decremented. Only the properties product_id, quantity and inventory_id from the incoming productItemWO are evaluated. All other incoming product item properties are ignored.

Url

POST http://hostname:port/dw/shop/v15_1/basket/{id}/add

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

ProductItem

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The id of the requested basket. Only 'this' is allowed.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidMessageException   Thrown if the request body is malformed, the product_id length is larger than 100 characters, or the quantity exceeds the range 0.01 to 999.00.
400 InvalidProductItemException

productId (String)

Thrown if the product_id is unknown, the product type is not supported (Master, Set), or no price is available.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown if the product item is not available.
400 InvalidProductItemException

productId (String)

Thrown if product_id is unknown, the product type is not supported (Master, Set), or no price is available.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown in case a product is not available anymore.
404 NotFoundException   Thrown if the basket is requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterAdd (basket : Basket , productItem : ProductItem ) : Status

It is called after the productItem was added to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
productItem - the productItem document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeAdd

beforeAdd (basket : Basket , productItem : ProductItem ) : Status

It is called before the productItem is added to the basket.

Parameters:
basket - the basket to add the productItem.
productItem - the productItem document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

#
# Example 1: Add product to basket with default inventory list
#
REQUEST:
POST /dw/shop/v15_1/basket/this/add HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp
Content-Length: 67

{
  "product_id" : "007",
  "quantity" : 1.00
}

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: fcee85e5d6ae1a6de35c6a47a7a967b923067faa095af7aedc145ba0d35d13a9
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 100.00,
  "product_total" : 100.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" : 
  [
    {
      "product_id" : "007",
      "item_text" : "Product PS3",
      "quantity" : 1.00,
      "product_name" : "PS3",
      "base_price" : 100.00,
      "price" : 100.00
    }
  ]
}

#
# Example 2: Add product to basket with special inventory list id 
#
REQUEST:
POST /dw/shop/v15_1/basket/this/add HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp
Content-Length: 67

{
  "product_id" : "456",
  "quantity" : 1.00
  "inventory_id" : "inventory_store_store4",
}

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "product_sub_total" : 240.00,
  "product_total" : 240.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" : 
  [
    {
      "product_id" : "007",
      "item_text" : "Product PS3",
      "quantity" : 1.00,
      "product_name" : "PS3",
      "base_price" : 100.00,
      "price" : 100.00
    },
    {
      "product_id" : "123",
      "item_text" : "Product foo",
      "quantity" : 2.00,
      "product_name" : "foo",
      "base_price" : 30.00,
      "price" : 60.00
    },
    {
      "product_id" : "456",
      "item_text" : "Product bar",
      "quantity" : 1.00,
      "product_name" : "bar",
      "inventory_id" : "inventory_store_store4",
      "base_price" : 40.00,
      "price" : 40.00
    },
    {
      "product_id" : "789",
      "item_text" : "Product incognito",
      "quantity" : 1.00,
      "product_name" : "incognito",
      "base_price" : 40.00,
      "price" : 40.00
    }
  ]
}

Get Basket Checkout

Returns the complete set of basket information, including address and shipping information.

Url

GET https://hostname:port/dw/shop/v15_1/basket/{id}/checkout

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String id the resource id of the requested basket. Only 'this' is allowed.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Sample

REQUEST:
GET /dw/shop/v15_1/basket/this/checkout 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
ETag: 1d4558a9fdaee4679a0c1ba962b246865b0a32d12f0aa98d007b4cf4d2988c82
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "_flash" :
  [
    {
      "type" : "CustomerEmailRequired"
    },
    {
      "type" : "ShippingAddressRequired",
      "path" : "$.shipments[0]"
    },
    {
      "type" : "BillingAddressRequired"
    },
    {
      "type" : "ShippingMethodRequired",
      "path" : "$.shipments[0]"
    },
    {
      "type" : "PaymentMethodRequired"
    }
  ],
  "currency" : "USD",
  "product_sub_total" : 96.00,
  "product_total" : 86.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" :
  [
    {
      "product_id" : "123",
      "item_text" : "Product foo",
      "quantity" : 2.00,
      "product_name" : "foo",
      "base_price" : 30.00,
      "price" : 60.00
    },
    {
      "product_id" : "456",
      "item_text" : "Product foo",
      "quantity" : 1.00,
      "product_name" : "bar",
      "base_price" : 40.00,
      "price" : 40.00,
      "price_adjustments" :
      [
        {
          "promotion_id" : "10% off",
          "promotion_link" : "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
          "item_text" : "10% off",
          "price" : -4.00
        }
      ]
    }
  ],
  "shipments" :
  [
    { "id" : "default" }
  ],
  "order_price_adjustments" :
  [
    {
      "promotion_id" : "10$ off",
      "promotion_link" : "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
      "item_text" : "10$ off",
      "price" : -10.00
    }
  ]
}

Create Basket Payment Instrument

Creates a new payment instrument for the basket. This payment instrument must define a payment method. The current basket is retrieved.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/payment_instruments

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

OrderPaymentInstrumentRequest

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String the basket ID  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPaymentMethodException

paymentMethodId (String)

Indicates that the requested payment method is unknown or not applicable.
404 NotFoundException   Indicates the basket was requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterCreatePaymentInstrument (basket : Basket , orderPaymentInstrument : OrderPaymentInstrument , add : OrderPaymentInstrumentRequest ) : Status

It is called after the payment instrument was applied to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
orderPaymentInstrument - the order payment instrument
add - the payment instrument document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeCreatePaymentInstrument

beforeCreatePaymentInstrument (basket : Basket , add : OrderPaymentInstrumentRequest ) : Status

It is called before an order payment instrument is set to the basket.

Parameters:
basket - the basket to set the payment instrument.
add - the payment instrument document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/payment_instruments HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8

{
  "payment_method_id" : "BANK_TRANSFER",
  "amount" : 500.00,
  "payment_bank_account:
  {
    "drivers_license" : "7s56Ts3n53",
    "number" : "123456789"
  }
}

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "payment_instruments" : [
  {
    "uuid" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "etag" : "4d48d1ec18cd88c046f889ff3da6ce7915554a88493d597de59cda31b49707d8",
    "payment_bank_account:
    {
      "masked_drivers_license" : "******3n53",
      "masked_number" : "*****6789",
    },
    "payment_method_id" : "BANK_TRANSFER",
    "amount" : 500.00
  }],
  "order_total" : 0.00,
  "payment_method" : 
  {
    "id" : "BANK_TRANSFER",
    "name" : "Bank Transfer"
  },
  "product_sub_total" : 0.00,
  "product_total" : 0.00,
  "shipments" : [
  {
    "shipping_items" : [
    {
      "adjusted_price" : 0.00,
      "item_text" : "Shipping",
      "price" : null
    }]
  }],
  "shipping_total" : 0.00,
  "tax_total" : 0.00
}
 
# 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: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":
  {
    "type":"InvalidPaymentMethodException",
    "message":"Payment method with id 'UNKNWON_PAYMENT_METHOD' is unknown or not applicable to basket."
  }
}

Delete Payment Instrument

Deletes a payment instrument with the uuid from the URL from the basket. The current basket is retrieved.

Url

DELETE https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/payment_instruments/{uuid}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The basket ID ('this')  
uuid String the UUID of the payment instrument, gotten from the URL  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Indicates that either the basket was requested by any identifier other than 'this', or that the payment instrument is not contained by the basket.

Customization

This Resource supports server-side customization.

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

afterDeletePaymentInstrument (basket : Basket ) : Status

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

Parameters:
basket - the basket the payment instrument was removed from
paymentInstrument - the payment instrument to be deleted
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeDeletePaymentInstrument

beforeDeletePaymentInstrument (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:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
DELETE /dw/shop/v15_1/basket/this/checkout/payment_instruments/ik237j324asd32 HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "order_total" : 0.00,
  "payment_method" : 
  {
    "id" : "BANK_TRANSFER",
    "name" : "Bank Transfer"
  },
  "product_sub_total" : 0.00,
  "product_total" : 0.00,
  "shipments" : [
  {
    "shipping_items" : [
    {
      "adjusted_price" : 0.00,
      "item_text" : "Shipping",
      "price" : null
    }]
  }],
  "shipping_total" : 0.00,
  "tax_total" : 0.00
}

# in case of 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: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":
  {
    "type":"NotFoundException",
    "message":"The payment instrument with uuid 'ik237j324asd32' was not found."
  }
}

Update Payment Instrument

Updates a payment instrument with the uuid from the URL in the current basket. The current basket is retrieved.

Url

PATCH https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/payment_instruments/{uuid}

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

OrderPaymentInstrumentRequest

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The basket ID ('this')  
uuid String the UUID of the payment instrument, gotten from the URL  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPaymentMethodException

paymentMethodId (String)

Indicates that the requested payment method is unknown or not applicable.
400 InvalidPaymentMethodDeletionException   Indicates forbidden access to payment_method_id property.
404 NotFoundException   Indicates that either the basket was requested by any identifier other than 'this', or that the payment instrument is not contained by the basket.

Customization

This Resource supports server-side customization.

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

afterUpdatePaymentInstrument (basket : Basket , orderPaymentInstrument : OrderPaymentInstrument , update : OrderPaymentInstrumentRequest ) : Status

It is called after the payment instrument was updated in the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
orderPaymentInstrument - the order payment instrument
update - the payment instrument update document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeUpdatePaymentInstrument

beforeUpdatePaymentInstrument (basket : Basket , orderPaymentInstrument : OrderPaymentInstrument , update : OrderPaymentInstrumentRequest ) : Status

It is called before an order payment instrument is updated in the basket.

Parameters:
basket - the basket to update the payment instrument in
orderPaymentInstrument - the actual order payment instrument
update - the payment instrument update document
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
PATCH /dw/shop/v15_1/basket/this/checkout/payment_instruments/ik237j324asd32 HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
If-Match : 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

{
  "payment_method_id" : "CREDIT_CARD.Visa",
  "amount" : 500.00,
  "payment_card" : 
  {
    "expiration_month" : 12,
    "expiration_year" : 2018,
    "holder" : "Jeff Lebowski",
    "number" : "4111111111111111",
    "security_code" : "1234"
  }
}

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "15.1",
  "currency" : "USD",
  "order_payment_instruments" : [
  {
    "uuid" : "ik237j324asd32",
    "etag" : "4d48d1ec18cd88c046f889ff3da6ce7915554a88493d597de59cda31b49707d8",
    "payment_method_id" : "CREDIT_CARD.Visa",
    "payment_card" : 
    {
      "card_type" : "Visa",
      "expiration_month" : 12,
      "expiration_year" : 2018,
      "holder" : "Jeff Lebowski",
      "masked_number" : "************1111",
    },
    "amount" : 500.00
  }],
  "order_total" : 0.00,
  "payment_method" : 
  {
    "id" : "CREDIT_CARD",
    "name" : "Credit Card"
  },
  "product_sub_total" : 0.00,
  "product_total" : 0.00,
  "shipments" : [
  {
    "shipping_items" : [
    {
      "adjusted_price" : 0.00,
      "item_text" : "Shipping",
      "price" : null
    }]
  }],
  "shipping_total" : 0.00,
  "tax_total" : 0.00
}
 
# 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: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":
  {
    "type":"NotFoundException",
    "message":"The payment instrument with uuid 'ik237j324asd32' was not found."
  }
}

Get Applicable Payment Methods

Returns a result object containing up to 100 applicable payment methods for the billing address and checkout amount.

Url

GET https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/payment_methods

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

PaymentMethodResult

Path Parameters

Parameter Type Description Constraints
id String The id of the requested basket. Only 'this' is allowed.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Sample

REQUEST:
GET /dw/shop/v15_1/basket/this/checkout/payment_methods HTTP/1.1
Host: example.com
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 158
{
  "_v":"15.1",
  "count":2,
  "total":2,
  "data":
  [{
    "id":"CREDIT_CARD",
    "name":"Credit Card",
    "description":"",
    "image":"http://anydomain.com/foo/bar.gif",
    "cards":[{
      "id":"CREDIT_CARD.Visa",
      "card_type":"Visa",
      "name":"Visa",
      "description":"Visa Card",
      "image":"http://anydomain.com/foo/visa.gif"
    },{
      "id":"CREDIT_CARD.Master",
      "card_type":"Master",
      "name":"Master Card",
      "description":"Master Card",
      "image":"http://anydomain.com/foo/master.gif"
    }]
  },{
    "id":"PayPal",
    "name":"Pay Pal",
    "description":"",
    "image":"http://anydomain.com/foo/paypal.gif"
  }]
}

Set Billing Address

Sets the billing address to basket. Any address validation errors result in a 400 fault message.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/set_billing_address

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

OrderAddress

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String id the resource id  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidBillingAddressException   Thrown in case address validation fails.
400 InvalidBillingAddressException   Thrown in case the billing address is not set or some address fields are missing.
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterSetBillingAddress (basket : Basket , orderAddress : OrderAddress ) : Status

It is called after the billing address was applied to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
orderAddress - the orderAddress document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeSetBillingAddress

beforeSetBillingAddress (basket : Basket , orderAddress : OrderAddress ) : Status

It is called before the billing address is applied to the basket.

Parameters:
basket - the basket to set the billing address.
orderAddress - the orderAddress document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/set_billing_address HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
If-Match: 2fc1e29fa964adc66126bd65faffd6015a7d11f126e6b45d0a1445bab5c4f6cb
 
{
  "salutation":"",
  "title":"",
  "company_name":"",
  "first_name":"",
  "second_name":"",
  "last_name":"",
  "postal_code":"",
  "address1":"",
  "address2":"",
  "city":"",
  "post_box":"",
  "country_code":"",
  "state_code":"",
  "phone":"",
  "suffix":""
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "_flash":[{
    "type":"PaymentMethodRequired"
  }],
  "currency":"USD",
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":5.00,
  "tax_total":9.10,
  "order_total":101.00,
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "shipments":[{
    "id":"default",
    "shipping_address":{
      "salutation":"",
      "title":"",
      "company_name":"",
      "first_name":"",
      "second_name":"",
      "last_name":"",
      "postal_code":"",
      "address1":"",
      "address2":"",
      "city":"",
      "post_box":"",
      "country_code":"",
      "state_code":"",
      "phone":"",
      "suffix":""
    },
    "shipping_method":{
      "id":"001",
      "name":"Ground",
      "description":"Order received within 7-10 business days"
    }}],
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  },
  "customer_info":{
    "email":"[email protected]"
  },
  "billing_address":{
    "salutation":"",
    "title":"",
    "company_name":"",
    "first_name":"",
    "second_name":"",
    "last_name":"",
    "postal_code":"",
    "address1":"",
    "address2":"",
    "city":"",
    "post_box":"",
    "country_code":"",
    "state_code":"",
    "phone":"",
    "suffix":""
  }
}
 
# 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
ETag: 2fc1e29fa964adc66126bd65faffd6015a7d11f126e6b45d0a1445bab5c4f6cb
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":{
    "type":"InvalidBillingAddressException",
    "message":"Invalid billing address."
  }
}

Set Customer Information

Sets the customer information for the basket. Any customer email validation errors result in a 400 fault message.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/set_customer_info

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

CustomerInfo

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String id the resource id  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerInformationException   Thrown in case the customer information email is empty or not a valid email address.
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

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

It is called after the customer info was applied to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
customerInfo - the customerInfo document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeSetCustomerInfo

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

It is called before the customer info is applied to the basket.

Parameters:
basket - the basket to set the customer information.
customerInfo - the customerInfo document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/set_customer_info HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
If-Match: 186706b38cc0976285c47945c8b64231ae0250fa8128db69781a3586150c9950
 
{
  "email":"[email protected]"
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: "8d6c1714.6173dad91c40824a3f862b4c75ad11ac0dd41690bab1e99179c1089"
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "_flash":[{
    "type":"ShippingAddressRequired",
    "path" : "$.shipments[0]"
  },{
    "type":"BillingAddressRequired"
  },{
    "type":"ShippingMethodRequired",
    "path" : "$.shipments[0]"
  },{
    "type":"PaymentMethodRequired"
  }],
  "currency":"USD",
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":null,
  "tax_total":null,
  "order_total":null,
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "shipments":[
    "id":"default"
  ],
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  },
  "customer_info":{
    "email":"[email protected]"
  }]
}
# 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
ETag: 186706b38cc0976285c47945c8b64231ae0250fa8128db69781a3586150c9950
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":{
    "type":"InvalidCustomerInformationException",
    "message":"Invalid customer email."
  }
}

Set Shipping Address

Sets the shipping address to baskets default shipment.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/set_shipping_address

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

OrderAddress

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The resource id.  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidShippingAddressException

shipmentId (String)

Thrown if address validation fails.
404 NotFoundException   Thrown if the basket was requested by an identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterSetShippingAddress (basket : Basket , orderAddress : OrderAddress ) : Status

It is called after the shipping address was applied to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
orderAddress - the orderAddress document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeSetShippingAddress

beforeSetShippingAddress (basket : Basket , orderAddress : OrderAddress ) : Status

It is called before the shipping address is applied to the basket.

Parameters:
basket - the basket to set the shipping address.
orderAddress - the oderAddress document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/set_shipping_address HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
Content-Length: 67
If-Match: 8d6c1714.6173dad91c40824a3f862b4c75ad11ac0dd41690bab1e99179c1089
 
{
  "salutation":"",
  "title":"",
  "company_name":"",
  "first_name":"",
  "second_name":"",
  "last_name":"",
  "postal_code":"",
  "address1":"",
  "address2":"",
  "city":"",
  "post_box":"",
  "country_code":"",
  "state_code":"",
  "phone":"",
  "suffix":""
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 2fc1e29fa964adc66126bd65faffd6015a7d11f126e6b45d0a1445bab5c4f6cb
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 187
 
{
  "_v":"15.1",
  "_flash":[{
    "type":"BillingAddressRequired"
  },{
    "type":"ShippingMethodRequired",
    "path" : "$.shipments[0]"
  },{
    "type":"PaymentMethodRequired"
  }],
  "currency":"USD",
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":null,
  "tax_total":null,
  "order_total":null,
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "shipments":[{
    "id":"default",
    "shipping_address":{
      "salutation":"",
      "title":"",
      "company_name":"",
      "first_name":"",
      "second_name":"",
      "last_name":"",
      "postal_code":"",
      "address1":"",
      "address2":"",
      "city":"",
      "post_box":"",
      "country_code":"",
      "state_code":"",
      "phone":"",
      "suffix":""
    }}],
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  },
  "customer_info":{
    "email":"[email protected]"
  }]
}
 
# 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
ETag: 8d6c1714.6173dad91c40824a3f862b4c75ad11ac0dd41690bab1e99179c1089
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":{
    "type":"InvalidShippingAddressException",
    "message":"Invalid shipping address."
  }
}

Set Shipping Method

Sets the shipping method for the basket's default shipment. If the shipping method is unknown or disabled, this action returns a 400 fault. If the shipping method is not applicable to all items in the basket, this action returns a 400 fault. If the shipping method is not applicable for the shipping address, this action returns a 400 fault. If the shipping method is restricted to certain address and no shipping address is defined, this action returns a 400 fault. Otherwise, this action sets the shipping method.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/set_shipping_method

Formats

json, xml

Authentication

Name Description
None No authentication.

Request Document

ShippingMethod

Response Document

Basket

Path Parameters

Parameter Type Description Constraints
id String The resource id.  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidShippingMethodException   Thrown if the requested shipping method is unknown or is not applicable.
400 InvalidShippingMethodException   Thrown if the shipping method is not set or is invalid.
400 InvalidMessageException   Thrown if the shipping method id length is larger than 256 characters.
404 NotFoundException   Thrown if the basket was requested by an identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterSetShippingMethod (basket : Basket , shippingMethod : ShippingMethod ) : Status

It is called after the shipping method was applied to the basket. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the updated basket, must be (re)calculated.
shippingMethod - the shippingMethod document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeSetShippingMethod

beforeSetShippingMethod (basket : Basket , shippingMethod : ShippingMethod ) : Status

It is called before the shipping method is applied to the basket.

Parameters:
basket - the basket to set the shipping method.
shippingMethod - the shippingMethod document.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/set_shipping_method HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
If-Match: 8d6c1714.6173dad91c40824a3f862b4c75ad11ac0dd41690bab1e99179c1089
{
  "id":"001"                    // only "id" is considered, all other properties are ignored
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: ccad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd43ac5
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "_flash":[{
    "type":"BillingAddressRequired"
  },{
    "type":"PaymentMethodRequired"
  }],
  "currency":"USD",
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":5.00,
  "tax_total":9.10,
  "order_total":101.00,
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "shipments":[{
    "id":"default",
    "shipping_address":{
      "salutation":"",
      "title":"",
      "company_name":"",
      "first_name":"",
      "second_name":"",
      "last_name":"",
      "postal_code":"",
      "address1":"",
      "address2":"",
      "city":"",
      "post_box":"",
      "country_code":"",
      "state_code":"",
      "phone":"",
      "suffix":""
    },
    "shipping_method":{
      "id":"001",
      "name":"Ground",
      "description":"Order received within 7-10 business days"
    }}],
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  },
  "customer_info":{
    "email":"[email protected]"
  }]
}
 
# in case of failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: 045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 38
 
{
  "_v":"15.1",
  "fault":{
    "type":"InvalidShippingMethodException",
    "message":"Shipping method with id 'foo' is unknown or not applicable to basket."
  }
}

Get Applicable Shipping Methods

Returns a result object containing up to 100 applicable shipping methods for the default shipment shipping address and product items.

Url

GET https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/shipping_methods

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

ShippingMethodResult

Path Parameters

Parameter Type Description Constraints
id String The id of the requested basket. Only 'this' is allowed.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Sample

REQUEST:
GET /dw/shop/v15_1/basket/this/checkout/shipping_methods HTTP/1.1
Host: example.com
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 158
{
  "_v":"15.1",
  "count":2,
  "total":2,
  "data":
  [{
    "id":"001",
    "name":"Ground",
    "description":"Order received within 7-10 business days",
    "price":5.99
  },{
    "id":"002",
    "name":"2-Day Express",
    "description":"Order received in 2 business days",
    "price":9.99
  }]
}

Submit Basket

Creates an order with status CREATED out of the basket. The order is not yet placed. This action returns a 400 fault in case any basket or checkout information are missing or invalid.

Url

POST https://hostname:port/dw/shop/v15_1/basket/{id}/checkout/submit

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Order

Path Parameters

Parameter Type Description Constraints
id String the resource id  

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 EmptyBasketException   Thrown in case the basket doesn't contain any item.
400 InvalidCustomerInformationException   Thrown in case the customer information email is empty or not an email address.
400 InvalidShippingAddressException

shipmentId (String)

Thrown in case the shipping address is not set or some address fields are missing.
400 InvalidShippingMethodException   Thrown in case the shipping method is not set or invalid.
400 InvalidBillingAddressException   Thrown in case the billing address is not set or some address fields are missing.
400 InvalidPaymentMethodException

paymentMethodId (String)

Thrown in case the payment method is not set or invalid.
400 InvalidProductItemException

productId (String)

Thrown if product_id is unknown, the product type is not supported (Master, Set), or no price is available.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown if the product_item is not available.
400 InvalidOptionItemException   Thrown in case an option item is invalid.
400 InvalidCouponItemException

couponCode (String)

Thrown in case a coupon code or item is invalid.
404 NotFoundException   Thrown in case a basket was requested by any identifier other than 'this'.

Customization

This Resource supports server-side customization.

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

afterSubmit (order : Order , basket : Basket ) : Status

It is called after the new order was created.

Parameters:
order - the new created order.
basket - the original basket
Returns:
  • Status.OK for success.
  • Status.ERROR for error.
dw.ocapi.shop.basket.beforeSubmit

beforeSubmit (basket : Basket ) : Status

It is called before the new order is created. The default implementation of this hook calls the {@link #calculate(Basket)} hook.

Parameters:
basket - the basket to create an order from, must be (re)calculated.
Returns:
  • Status.OK for success.
  • Status.ERROR for error.

Sample

REQUEST:
POST /dw/shop/v15_1/basket/this/checkout/submit HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
If-Match: ccad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd43ac5

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: y4ad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd438kl
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "creation_date":"2013-09-28T04:02Z",
  "customer_info":{
    "email":"[email protected]"
  },
  "currency":"USD",
  "order_no":"1234567890",
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
  "payment_method":{
    "id":"CREDIT_CARD.Visa",
    "card_type":"Visa",
    "name":"Visa",
    "description":"Visa Card",
    "image":"http://anydomain.com/foo/visa.gif"
  },
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "http://example.com/dw/shop/v15_1/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":5.00,  
  "shipments":[{
    "id":"default",
    "shipping_address":{
      "salutation":"",
      "title":"",
      "company_name":"",
      "first_name":"",
      "second_name":"",
      "last_name":"",
      "postal_code":"",
      "address1":"",
      "address2":"",
      "city":"",
      "post_box":"",
      "country_code":"",
      "state_code":"",
      "phone":"",
      "suffix":""
    },
    "shipping_method":{
      "id":"001",
      "name":"Ground",
      "description":"Order received within 7-10 business days"
    }}],
  "status":"pending",
  "tax_total":9.10
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
ETag: ccad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd43ac5
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"15.1",
  "fault":{
    "type":"ProductItemNotAvailable",
    "message":"Product '123' is not available for quantity '2'."
  }
}