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

Orders resource (Shop API 23.2)

Summary

Http Method	Resource	Description
POST	/orders	Submits an order based on a prepared basket. Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. The only considered value from the request body is basket_id.
PUT	/orders/{order_no}	Submits an order with a given order number, based on a prepared basket. The only considered value from the request body is basket_id.
GET	/orders/{order_no}	Gets information for an order.
PATCH	/orders/{order_no}	Update an order. Considered fields for update are status (same status transitions are possible as for dw.order.Order.setStatus(int status) plus CREATED to FAILED) and custom properties. During the call the correct channel type will be assured to be set for the order in a successful call. Without agent context the channel type will be storefront otherwise callcenter.
POST	/orders/{order_no}/notes	Adds a note to an existing order.
GET	/orders/{order_no}/notes	Retrieves notes for an order.
DELETE	/orders/{order_no}/notes/{note_id}	Removes an order note.
POST	/orders/{order_no}/payment_instruments	Adds a payment instrument to an order. It is possible either to supply the full payment information or only a customer payment instrument id and amount. In case the customer payment instrument id was set all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information. An attempt is made to authorize the order by passing it to the authorize or authorizeCreditCard hook. Details: The payment instrument is added with the provided details or the details from the customer payment instrument. The payment method must be applicable for the order see `GET /baskets/{basket_id}/payment_methods`, if the payment method is 'CREDIT_CARD' `a payment_card` must be specified in the request. Order authorization: To authorize the order one of two possible customization hooks is called and an `dw.order.OrderPaymentInstrument` is passed as an input argument. Which hook is called? If the request includes a `payment_card` or the `dw.order.OrderPaymentInstrument` contains a `creditCardType` the customization hook `dw.order.payment.authorizeCreditCard` is called. See `dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status`. Otherwise `dw.order.payment.authorize` is called. See `dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status`. What is the `dw.order.OrderPaymentInstrument` input argument passed to the hook? If the request contains a `customer_payment_instrument_id` the `dw.order.OrderPaymentInstrument` is copied from the customer payment instrument (An exception is thrown if none was found). Otherwise the data from the request document is passed (`payment_card` or `payment_bank_account` etc. information). Note: the `amount` and the `security_code` (cvn) contained in the `payment_card` data will be propagated if available to `dw.order.payment.authorizeCreditCard` even if the `dw.order.OrderPaymentInstrument` is resolved from a customer payment instrument. Customization hook `dw.ocapi.shop.order.afterPostPaymentInstrument` is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling `dw.order.OrderMgr.placeOrder(order : Order)` in the scripting API) results in the order being changed to status `NEW` and prepared for export.
PATCH	/orders/{order_no}/payment_instruments/{payment_instrument_id}	Updates a payment instrument of an order and passes the order and updated payment instrument to the correct payment authorizeCreditcard or authorize hook. Details: The payment instrument is updated with the provided details. The payment method must be applicable for the order see `GET /baskets/{basket_id}/payment_methods`, if the payment method is 'CREDIT_CARD' a `payment_card` must be specified in the request. Order authorization: To authorize the order one of two possible customization hooks is called and an `dw.order.OrderPaymentInstrument` is passed as an input argument. Which hook is called? If the request includes a `payment_card` or the `dw.order.OrderPaymentInstrument` contains a `creditCardType` the customization hook `dw.order.payment.authorizeCreditCard` is called. See `dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status`. Otherwise `dw.order.payment.authorize` is called. See `dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status`. What is the `dw.order.OrderPaymentInstrument` input argument passed to the hook? If the request contains a `customer_payment_instrument_id` the `dw.order.OrderPaymentInstrument` is copied from the customer payment instrument (An exception is thrown if none was found). Otherwise the data from the request document is passed (`payment_card` or `payment_bank_account` etc. information). Note: the `amount` and the `security_code` (cvn) contained in the `payment_card` data will be propagated if available to `dw.order.payment.authorizeCreditCard` even if the `dw.order.OrderPaymentInstrument` is resolved from a customer payment instrument. Customization hook `dw.ocapi.shop.order.afterPatchPaymentInstrument` is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling `dw.order.OrderMgr.placeOrder(order : Order)` in the scripting API) results in the order being changed to status `NEW` and prepared for export.
DELETE	/orders/{order_no}/payment_instruments/{payment_instrument_id}	Removes a payment instrument of an order.
GET	/orders/{order_no}/payment_methods	Gets the applicable payment methods for an existing order considering the open payment amount only.

Submit basket

Submits an order based on a prepared basket. Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. The only considered value from the request body is basket_id.

Url

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

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

Order

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`GiftCertificateCreationException`		Thrown if a failure during the creation of a gift certificate for a gift certificate item.
400	`InvalidBasketIdException`		Indicates that the basket id in the request body is null or empty.
400	`InvalidProductItemException`	productId (String)	Indicates an invalid product item.
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	`ProductItemNotAvailableException`	productId (String) quantity (Decimal)	Thrown if a product item is not available.
400	`InvalidCustomerException`		Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
400	`ValidationException`	validationMessage (String) validationPath (String) validationType (String)	Indicates that the basket contains flashes.
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.order.beforePOST	beforePOST (basket : Basket ) : Status The function is called before an order is created for the basket. Parameters: basket - the basket based on which the order is created Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.afterPOST	afterPOST (order : Order ) : Status The function is called after an order was created from the basket. Parameters: order - the order that was created for the basket Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.modifyPOSTResponse	modifyPOSTResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order 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:
POST /dw/shop/v23_2/orders HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
  "basket_id" : "cdxEQiWbNVZZaaaadhKBc35gtp"
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "adjusted_merchandize_total_tax" : 0.05,
   "adjusted_shipping_total_tax" : 0.00,
   "billing_address" : {
      "city" : "Boston",
      "country_code" : "US",
      "first_name" : "Jeff",
      "full_name" : "Jeff Lebowski",
      "last_name" : "Lebowski",
      "c_strValue" : "cTest"
   },
   "creation_date" : "2014-11-06T13:36Z",
   "currency" : "USD",
   "customer_info" : {
      "customer_no" : "jlebowski",
      "email" : "[email protected]"
   },
   "merchandize_total_tax" : 5.00,
   "order_no" : "00000101",
   "order_token" : "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
   "order_total" : 1.06,
   "payment_instruments" : [
      {
         "amount" : 1.00,
         "payment_bank_account" : {
            "drivers_license_last_digits" : "ense",
            "drivers_license_masked" : "**************ense",
            "number_last_digits" : "mber",
            "number_masked" : "*************mber"
         },
         "id" : "cdKCIiWbNVndQaaadhlSa35gtp",
         "payment_card" : {
            "card_type" : "testVisa",
            "credit_card_expired" : false,
            "expiration_month" : 4,
            "expiration_year" : 21.2,
            "holder" : "TestPerson",
            "number_last_digits" : "mber",
            "number_masked" : "**********mber"
         },
         "payment_method_id" : "OCAPI_Payment_Simple"
      }
   ],
   "product_items" : [
      {
         "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" : 1.00,
         "product_id" : "SimpleProduct",
         "product_name" : "Simple Product",
         "quantity" : 1.00,
         "tax" : 5.00,
         "tax_basis" : 16.49,
         "tax_class_id" : null,
         "tax_rate" : 0.05,
         "item_id" : "cdHBEiWbNV9ZcaaadhrCk35gtp",
         "c_strValue" : "Test"
      }
   ],
   "product_sub_total" : 16.49,
   "product_total" : 1.00,
   "shipments" : [
      {
         "id" : "me",
         "shipping_address" : {
            "city" : "Boston",
            "country_code" : "US",
            "first_name" : "Jeff",
            "full_name" : "Jeff Lebowski",
            "last_name" : "Lebowski",
            "c_strValue" : "cTest"
         },
         "shipping_method" : {
            "description" : {
               "default" : "The base shipping method."
            },
            "id" : "BaseShippingMethod",
            "name" : {
               "default" : "Base Shipping Method"
            },
            "price" : 0.01,
            "c_somestring" : "ShippingMethod String Value"
         }
      }
   ],
   "shipping_items" : [
      {
         "adjusted_tax" : 0.00,
         "base_price" : 0.01,
         "item_text" : "Shipping",
         "price" : 0.01,
         "price_after_item_discount" : 0.01,
         "shipment_id" : "me",
         "tax" : 0.00,
         "tax_basis" : 0.01,
         "tax_class_id" : "DefaultTaxClass",
         "tax_rate" : 0.05,
         "item_id" : "devgoiWbNVc92aaadhrSk35gtp"
      }
   ],
   "shipping_total" : 0.01,
   "shipping_total_tax" : 0.00,
   "status" : "created",
   "tax_total" : 0.05,
   "c_strValue" : "before submit basket",
   "c_textValue" : "after submit basket"
}


# in case of validation failure:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : {
      "type" : "BasketNotFoundException",
      "message" : "No basket with ID '123' was found."
   }
}

Submit basket with given order number

Submits an order with a given order number, based on a prepared basket. The only considered value from the request body is basket_id.

Url

PUT https://hostname:port/dw/shop/v23_2/orders/{order_no}

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

Basket

Response Document

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	The order number to assign to the new order.	maxLength=50, minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`GiftCertificateCreationException`		Thrown if a failure during the creation of a gift certificate for a gift certificate item.
400	`InvalidBasketIdException`		Indicates that the basket id in the request body is null or empty.
400	`InvalidProductItemException`	productId (String)	Indicates an invalid product item.
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	`ProductItemNotAvailableException`	productId (String) quantity (Decimal)	Thrown if a product item is not available.
400	`InvalidCustomerException`		Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
400	`ValidationException`	validationMessage (String) validationPath (String) validationType (String)	Indicates that the basket contains flashes.
404	`BasketNotFoundException`	basketId (String)	Indicates that the basket with the given basket id is unknown.
409	`DuplicateOrderNumberException`	orderNo (String)	409 CONFLICT Indicates that the requested order number is already allocated to an existing order.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.beforePUT	beforePUT (ctor : Basket ) : Status The function is called before an order is created for the basket with the caller supplying the order number. Parameters: basket - the basket based on which the order is created Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.afterPUT	afterPUT (order : Order ) : Status The function is called after an order is created for the basket with the caller supplying the order number. Parameters: order - the order that was created for the basket Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.modifyPUTResponse	modifyPUTResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.beforePUT

beforePUT (ctor : Basket ) : Status

The function is called before an order is created for the basket with the caller supplying the order number.

Parameters:: basket - the basket based on which the order is created
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.afterPUT

afterPUT (order : Order ) : Status

The function is called after an order is created for the basket with the caller supplying the order number.

Parameters:: order - the order that was created for the basket
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.modifyPUTResponse

modifyPUTResponse (order : Order , orderResponse : Order ) : Status

Parameters:: order - target order; orderResponse - order response object
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
PUT /dw/shop/v23_2/orders/123OrderNumber456 HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
  "basket_id" : "cdxEQiWbNVZZaaaadhKBc35gtp"
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
...
   "order_no" : "123OrderNumber456",
   "order_token" : "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
...
}


# 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 'cdxEQiWbNVZZaaaadhKBc35gtp' was found."
   }
}

# in case order with order number exists:

RESPONSE:
HTTP/1.1 409 CONFLICT
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" : "DuplicateOrderNumberException",
      "message" : "An order with order number '123OrderNumber456' already exists."
   }
}

Get order

Gets information for an order.

Url

GET https://hostname:port/dw/shop/v23_2/orders/{order_no}

Formats

json, xml

Authentication

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

Response Document

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	the order number	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.beforeGET	beforeGET (orderNo : String ) : Status The function is called before the request will be processed. Parameters: orderNo - the order number Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.modifyGETResponse	modifyGETResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.beforeGET

beforeGET (orderNo : String ) : Status

The function is called before the request will be processed.

Parameters:: orderNo - the order number
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.modifyGETResponse

modifyGETResponse (order : Order , orderResponse : Order ) : Status

Parameters:: order - target order; orderResponse - order response object
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/orders/1234567890 HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate

{
  "_v" : "23.2",
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "_type":"order",
  "creation_date":"2014-06-15T04:02Z",
  "customer_info":{
    "email":"[email protected]"
  },
  "currency":"USD",
  "order_no":"1234567890",
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "https://example.com/dw/shop/v23_2/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
  "payment_instruments" : [
  {
    "payment_instrument_id" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "payment_method_id" : "CREDIT_CARD",
    "payment_card" : 
    {
      "card_type" : "Visa",
      "expiration_month" : 12,
      "expiration_year" : 21.2,
      "holder" : "Jeff Lebowski",
      "masked_number" : "************1111",
    },
    "amount" : 0.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": "https://example.com/dw/shop/v23_2/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":"created",
  "tax_total":9.10
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource 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" : "23.2",
  "_type":"fault",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '1234567890' was found."
  }
}

Update order

Update an order.

Considered fields for update are status (same status transitions are possible as for dw.order.Order.setStatus(int status) plus CREATED to FAILED) and custom properties. During the call the correct channel type will be assured to be set for the order in a successful call. Without agent context the channel type will be storefront otherwise callcenter.

Url

PATCH https://hostname:port/dw/shop/v23_2/orders/{order_no}

Formats

json, xml

Authentication

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

Request Document

Order

Response Document

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	the order number	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`NotFoundException`		Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.beforePATCH	beforePATCH (order : Order , orderInput : Order ) : Status The function is called before an order is patched. Parameters: order - the order which will be changed orderInput - the input data from the REST call Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.afterPATCH	afterPATCH (order : Order , orderInput : Order ) : Status The function is called after an order was patched. Parameters: order - the order that was changed orderInput - the input data from the REST call Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.modifyPATCHResponse	modifyPATCHResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.beforePATCH

beforePATCH (order : Order , orderInput : Order ) : Status

The function is called before an order is patched.

Parameters:: order - the order which will be changed; orderInput - the input data from the REST call
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.afterPATCH

afterPATCH (order : Order , orderInput : Order ) : Status

The function is called after an order was patched.

Parameters:: order - the order that was changed; orderInput - the input data from the REST call
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.modifyPATCHResponse

modifyPATCHResponse (order : Order , orderResponse : Order ) : Status

Parameters:: order - target order; orderResponse - order response object
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /dw/shop/v23_2/orders/1234567890 HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "status" : "replaced",
  "c_replaced" : true
}

# 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",
  "_type":"order",
  "creation_date":"2014-06-15T04:02Z",
  "customer_info":{
    "email":"[email protected]"
  },
  "currency":"USD",
  "order_no":"1234567890",
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "https://example.com/dw/shop/v23_2/promotions/10_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
  "payment_instruments" : [
  {
    "payment_instrument_id" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "payment_method_id" : "CREDIT_CARD",
    "payment_card" : 
    {
      "card_type" : "Visa",
      "expiration_month" : 12,
      "expiration_year" : 21.2,
      "holder" : "Jeff Lebowski",
      "masked_number" : "************1111",
    },
    "amount" : 0.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": "https://example.com/dw/shop/v23_2/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":"replaced",
  "tax_total":9.10,
  "c_replaced" : true
}

# 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
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "statusFrom" : "CREATED",
         "statusTo" : "REPLACED"
      },
      "type" : "StatusTransitionNotPossibleException",
      "message" : "Status transition from 'CREATED' to 'REPLACED' not possible."
   }
}

Add a note to an order

Adds a note to an existing order.

Url

POST https://hostname:port/dw/shop/v23_2/orders/{order_no}/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

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	The id of the order to be modified.	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`OrderNotFoundException`	orderNumber (String)	Thrown if the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.note.beforePOST	beforePOST (orderNo : String , note : Note ) : Status The function is called before the request will be processed. Parameters: orderNo - The id of the order from which you want to retrieve notes. note - The note to be added. Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.note.modifyPOSTResponse	modifyPOSTResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.note.beforePOST

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

The function is called before the request will be processed.

Parameters:: orderNo - The id of the order from which you want to retrieve notes.; note - The note to be added.
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.note.modifyPOSTResponse

modifyPOSTResponse (order : Order , orderResponse : Order ) : Status

Parameters:: order - target order; orderResponse - order response object
Returns:: a non-null Status ends the hook execution

Sample

#
# Example: Add a note to an order
#
REQUEST:
POST /dw/shop/v23_2/orders/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" : "order",
...
   "notes" : { 
       "link" : "https://www.example.com/dw/shop/v23_2/orders/cdcM6iWbN5jyIaaadh5thrJrYj/notes"
    }
...
}

Get notes from an order

Retrieves notes for an order.

Url

GET https://hostname:port/dw/shop/v23_2/orders/{order_no}/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
order_no	String	The id of the order from which you want to retrieve notes.	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`OrderNotFoundException`	orderNumber (String)	Thrown if the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.notes.beforeGET	beforeGET (orderNo : String ) : Status The function is called before the request will be processed. Parameters: orderNo - The id of the order from which you want to retrieve notes. Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.notes.modifyGETResponse_v2	modifyGETResponse_v2 (order : Order , notesResultResponse : NotesResult ) : Status Parameters: order - the order the notes result retrieved for. notesResultResponse - notes result response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.notes.beforeGET

beforeGET (orderNo : String ) : Status

The function is called before the request will be processed.

Parameters:: orderNo - The id of the order from which you want to retrieve notes.
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.notes.modifyGETResponse_v2

modifyGETResponse_v2 (order : Order , notesResultResponse : NotesResult ) : Status

Parameters:: order - the order the notes result retrieved for.; notesResultResponse - notes result response object
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/orders/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 an order

Removes an order note.

Url

DELETE https://hostname:port/dw/shop/v23_2/orders/{order_no}/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

Order

Path Parameters

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

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number is unknown.
404	`NoteNotFoundException`	noteId (String)	Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.note.beforeDELETE	beforeDELETE (order : Order , note : Note ) : Status The function is called before a note is deleted. Parameters: order - the order note - the note to be removed Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.note.afterDELETE	afterDELETE (order : Order , note : Note ) : Status The function is called after a note is deleted. Parameters: order - the order note - the note to be removed Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.note.modifyDELETEResponse	modifyDELETEResponse (order : Order , orderResponse : Order , noteId : String ) : Status Parameters: order - target order orderResponse - order response object noteId - note id to delete Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.note.beforeDELETE

beforeDELETE (order : Order , note : Note ) : Status

The function is called before a note is deleted.

Parameters:: order - the order; note - the note to be removed
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.note.afterDELETE

afterDELETE (order : Order , note : Note ) : Status

The function is called after a note is deleted.

Parameters:: order - the order; note - the note to be removed
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.note.modifyDELETEResponse

modifyDELETEResponse (order : Order , orderResponse : Order , noteId : String ) : Status

Parameters:: order - target order; orderResponse - order response object; noteId - note id to delete
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /shop/v23_2/orders/00000029/notes/cdXTraOu6bXT6aaadll5tOJvce HTTP/1.1
Host: example.com
Authorization:Bearer 80a68fc6-945c-49e2-bfd6-abc9994de307
# 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" : "order",
...
   "notes" : 
   {
      "_type" : "simple_link",
      "link" : "https://example.com/dw/shop/v23_2/orders/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",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "fault" : 
   {
      "type" : "NoteNotFoundException",
      "message" : "The note 'NonExisting' could not be found."
   }
}

Add payment instrument to order

Adds a payment instrument to an order. It is possible either to supply the full payment information or only a customer payment instrument id and amount. In case the customer payment instrument id was set all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information. An attempt is made to authorize the order by passing it to the authorize or authorizeCreditCard hook.

Details:

The payment instrument is added with the provided details or the details from the customer payment instrument. The payment method must be applicable for the order see GET /baskets/{basket_id}/payment_methods, if the payment method is 'CREDIT_CARD' a payment_card must be specified in the request.
Order authorization:

To authorize the order one of two possible customization hooks is called and an dw.order.OrderPaymentInstrument is passed as an input argument.

Which hook is called?
- If the request includes a payment_card or the dw.order.OrderPaymentInstrument contains a creditCardType the customization hook dw.order.payment.authorizeCreditCard is called. See dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status.
- Otherwise dw.order.payment.authorize is called. See dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status.
What is the dw.order.OrderPaymentInstrument input argument passed to the hook?
- If the request contains a customer_payment_instrument_id the dw.order.OrderPaymentInstrument is copied from the customer payment instrument (An exception is thrown if none was found).
- Otherwise the data from the request document is passed (payment_card or payment_bank_account etc. information).
Note: the amount and the security_code (cvn) contained in the payment_card data will be propagated if available to dw.order.payment.authorizeCreditCard even if the dw.order.OrderPaymentInstrument is resolved from a customer payment instrument.
Customization hook dw.ocapi.shop.order.afterPostPaymentInstrument is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling dw.order.OrderMgr.placeOrder(order : Order) in the scripting API) results in the order being changed to status NEW and prepared for export.

Url

POST https://hostname:port/dw/shop/v23_2/orders/{order_no}/payment_instruments?skip_authorization={Boolean}

Formats

json, xml

Authentication

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

Request Document

OrderPaymentInstrumentRequest

Response Document

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	the order number	minLength=1

Query Parameters

Parameter	Type	Description	Constraints
skip_authorization	Boolean

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`InvalidOrderNumberException`		Indicates that the given order number is invalid.
400	`InvalidPaymentMethodIdException`	paymentMethodId (String)	Indicates that the provided payment method is invalid or not applicable.
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number is unknown.
404	`PaymentInstrumentNotFoundException`	paymentInstrumentId (String)	Indicates that a customer payment instrument could not be resolved based on the provided customer payment instrument id.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.validateOrder	validateOrder (order : Order ) : Status Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes: `exports.validateBasket = function() { order.addFlash( {type:"PaymentAuthorizationFailure", message:"Order was not successfully authorized.", path:"authorizations", details:{ "result":"reject", "reason":"invalid_credit_card"}});` Parameters: order - the modified order Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.modifyPOSTResponse	modifyPOSTResponse (order : Order , orderResponse : Order ) : Status Parameters: order - target order orderResponse - order response object Returns: a non-null Status ends the hook execution
dw.order.payment.authorize	authorize (order : Order , paymentDetails : OrderPaymentInstrument ) : Status Custom payment authorization - modify the order as needed. Prerequisite: An order has been created using the data api or via the storefront. Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this). Return Status.ERROR: Order is held, authorization needs to be repeated. Parameters: order - the order paymentDetails - specified payment details Returns: Status.OK successful authorization. Status.ERROR authorization failed.
dw.ocapi.shop.order.payment_instrument.beforePOST	beforePOST (order : Order , paymentInstrument : OrderPaymentInstrumentRequest ) : Status The function is called before a payment instrument is added to the order. Parameters: order - the modified order paymentInstrument - the payment instrument to be added to the order Returns: a non-null Status ends the hook execution
dw.order.payment.authorizeCreditCard	authorizeCreditCard (order : Order , paymentDetails : OrderPaymentInstrument , cvn : String ) : Status Custom payment authorization of a credit card - modify the order as needed. Prerequisite: An order has been created using the data api or via the storefront. Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this). Return Status.ERROR: Order is held, authorization needs to be repeated. Parameters: order - the order paymentDetails - specified payment details cvn - the credit card verification number Returns: Status.OK successful authorization. Status.ERROR authorization failed.
dw.ocapi.shop.order.payment_instrument.afterPOST	afterPOST (order : Order , paymentInstrument : OrderPaymentInstrumentRequest , successfullyAuthorized : boolean ) : Status The function is called after a payment instrument was added to the order. Parameters: order - the modified order paymentInstrument - the payment instrument which was added to the order successfullyAuthorized - was the payment instrument successfully authorized. Returns: a non-null Status ends the hook execution

Sample

REQUEST:
POST /shop/v23_2/orders/00000027/payment_instruments HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
{
  "amount": 2,
  "payment_card": {
    "number": "4111111111111111",
    "security_code": "112",
    "holder": "Ed Smith",
    "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-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "credit_card_token" : "00000021-2",
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "Ed Smith",
            "masked_number" : "***********1111",
            "number_last_digits" : "1111"
         },
         "payment_method_id" : "CREDIT_CARD",
         "payment_instrument_id" : "cdZnraOu6bcqwaaadlW5ROJu9Y",
      }
   ],
...
}

Updates payment instrument of order

Updates a payment instrument of an order and passes the order and updated payment instrument to the correct payment authorizeCreditcard or authorize hook.

Details:

The payment instrument is updated with the provided details. The payment method must be applicable for the order see GET /baskets/{basket_id}/payment_methods, if the payment method is 'CREDIT_CARD' a payment_card must be specified in the request.
Order authorization:

To authorize the order one of two possible customization hooks is called and an dw.order.OrderPaymentInstrument is passed as an input argument.

Which hook is called?
- If the request includes a payment_card or the dw.order.OrderPaymentInstrument contains a creditCardType the customization hook dw.order.payment.authorizeCreditCard is called. See dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status.
- Otherwise dw.order.payment.authorize is called. See dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status.
What is the dw.order.OrderPaymentInstrument input argument passed to the hook?
- If the request contains a customer_payment_instrument_id the dw.order.OrderPaymentInstrument is copied from the customer payment instrument (An exception is thrown if none was found).
- Otherwise the data from the request document is passed (payment_card or payment_bank_account etc. information).
Note: the amount and the security_code (cvn) contained in the payment_card data will be propagated if available to dw.order.payment.authorizeCreditCard even if the dw.order.OrderPaymentInstrument is resolved from a customer payment instrument.
Customization hook dw.ocapi.shop.order.afterPatchPaymentInstrument is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling dw.order.OrderMgr.placeOrder(order : Order) in the scripting API) results in the order being changed to status NEW and prepared for export.

Url

PATCH https://hostname:port/dw/shop/v23_2/orders/{order_no}/payment_instruments/{payment_instrument_id}?skip_authorization={Boolean}

Formats

json, xml

Authentication

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

Request Document

OrderPaymentInstrumentRequest

Response Document

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	the order number	minLength=1
payment_instrument_id	String	the id of the payment instrument to be updated	minLength=1

Query Parameters

Parameter	Type	Description	Constraints
skip_authorization	Boolean

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`PaymentInstrumentPermanentlyMaskedException`	paymentInstrumentId (String)	Indicates that the basket payment instrument with the given id already is permanently masked.
400	`InvalidPaymentMethodIdException`	paymentMethodId (String)	Indicates that the provided payment method is invalid or not applicable.
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number 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.order.payment_instrument.afterPATCH	afterPATCH (order : Order , paymentInstrument : OrderPaymentInstrument , newPaymentInstrument : OrderPaymentInstrumentRequest , successfullyAuthorized : boolean ) : Status The function is called after updating a payment instrument of an order. Parameters: order - the modified order paymentInstrument - the updated payment instrument newPaymentInstrument - the new payment instrument data successfullyAuthorized - was the payment instrument successfully authorized. Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.modifyPATCHResponse	modifyPATCHResponse (order : Order , orderResponse : Order , paymentInstrumentId : String ) : Status Parameters: order - target order orderResponse - order response object paymentInstrumentId - payment instrument id Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.beforePATCH	beforePATCH (order : Order , paymentInstrument : OrderPaymentInstrument , newPaymentInstrument : OrderPaymentInstrumentRequest ) : Status The function is called before updating a payment instrument of an order. Parameters: order - the modified order 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.order.validateOrder	validateOrder (order : Order ) : Status Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes: `exports.validateBasket = function() { order.addFlash( {type:"PaymentAuthorizationFailure", message:"Order was not successfully authorized.", path:"authorizations", details:{ "result":"reject", "reason":"invalid_credit_card"}});` Parameters: order - the modified order Returns: a non-null Status ends the hook execution
dw.order.payment.authorize	authorize (order : Order , paymentDetails : OrderPaymentInstrument ) : Status Custom payment authorization - modify the order as needed. Prerequisite: An order has been created using the data api or via the storefront. Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this). Return Status.ERROR: Order is held, authorization needs to be repeated. Parameters: order - the order paymentDetails - specified payment details Returns: Status.OK successful authorization. Status.ERROR authorization failed.
dw.order.payment.authorizeCreditCard	authorizeCreditCard (order : Order , paymentDetails : OrderPaymentInstrument , cvn : String ) : Status Custom payment authorization of a credit card - modify the order as needed. Prerequisite: An order has been created using the data api or via the storefront. Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this). Return Status.ERROR: Order is held, authorization needs to be repeated. Parameters: order - the order paymentDetails - specified payment details cvn - the credit card verification number Returns: Status.OK successful authorization. Status.ERROR authorization failed.

Sample

REQUEST:
PATCH /dw/shop/v23_2/orders/00000021/payment_instruments/cdZnraOu6bcqwaaadlW5ROJu9Y HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
{
  "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
  "amount": 2,
  "payment_card": {
    "number": "4111111111111111",
    "security_code": "112",
    "holder": "Ed Smith",
    "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-Length:124 
Content-Type:application/json;charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "credit_card_token" : "00000021-2",
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "Ed Smith",
            "masked_number" : "***********1111",
            "number_last_digits" : "1111"
         },
         "payment_method_id" : "CREDIT_CARD",
         "payment_instrument_id" : "cdZnraOu6bcqwaaadlW5ROJu9Y",
      }
   ],
...
}

Removes a payment instrument of an order

Removes a payment instrument of an order.

Url

DELETE https://hostname:port/dw/shop/v23_2/orders/{order_no}/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

Order

Path Parameters

Parameter	Type	Description	Constraints
order_no	String	the order number	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
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number 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.order.validateOrder	validateOrder (order : Order ) : Status Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes: `exports.validateBasket = function() { order.addFlash( {type:"PaymentAuthorizationFailure", message:"Order was not successfully authorized.", path:"authorizations", details:{ "result":"reject", "reason":"invalid_credit_card"}});` Parameters: order - the modified order Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.beforeDELETE	beforeDELETE (order : Order , paymentInstrument : OrderPaymentInstrument ) : Status The function is called before removing a payment instrument of an order. Parameters: order - the modified order paymentInstrument - the payment instrument to be removed Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.afterDELETE	afterDELETE (order : Order , paymentInstrument : OrderPaymentInstrument ) : Status The function is called after removing a payment instrument of an order. Parameters: order - the modified order paymentInstrument - the removed payment instrument Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_instrument.modifyDELETEResponse	modifyDELETEResponse (order : Order , orderResponse : Order , paymentInstrumentId : String ) : Status Parameters: order - target order orderResponse - order response object paymentInstrumentId - payment instrument id Returns: a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /dw/shop/v23_2/orders/00000029/payment_instruments/cdXTraOu6bXT6aaadll5tOJvce HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
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",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "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 an order

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

Url

GET https://hostname:port/dw/shop/v23_2/orders/{order_no}/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
order_no	String	the order number	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 order does not match the verified customer represented by the JWT, not relevant when using OAuth.
404	`OrderNotFoundException`	orderNumber (String)	Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.order.payment_methods.beforeGET	beforeGET (orderNumber : String ) : Status The function is called before the request will be processed. Parameters: orderNumber - the order number Returns: a non-null Status ends the hook execution
dw.ocapi.shop.order.payment_methods.modifyGETResponse_v2	modifyGETResponse_v2 (order : Order , paymentMethodResultResponse : PaymentMethodResult ) : Status Parameters: order - the order the payment method result retrieved for. paymentMethodResultResponse - payment method result response object Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.shop.order.payment_methods.beforeGET

beforeGET (orderNumber : String ) : Status

The function is called before the request will be processed.

Parameters:: orderNumber - the order number
Returns:: a non-null Status ends the hook execution

dw.ocapi.shop.order.payment_methods.modifyGETResponse_v2

modifyGETResponse_v2 (order : Order , paymentMethodResultResponse : PaymentMethodResult ) : Status

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

Sample

REQUEST:
GET /dw/shop/v23_2/orders/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,
               "c_somestring" : "PaymentCard String Value"
            },
            {
               "_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,
               "c_somestring" : "PaymentCard String Value"
            },
            ...
}

# 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" : "OrderNotFoundException",
      "message" : "No order with number 'non_existing_order' was found."
   }
}

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.