Orders Resource (Shop API 15.6)

Summary

Http Method Resource Description
GET /Orders/{Order_no} Gets information for an order.
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 Order

Gets information for an order.

Url

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

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

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.

Sample

REQUEST:
GET /dw/shop/v15_6/orders/1234567890 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
Content-Type: application/json;charset=UTF-8
ETag: y4ad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd438kl
Cache-Control: max-age=0,no-cache,no-store,must-revalidate

{
  "_v":"15.6",
  "_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/v15_6/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",
    "etag" : "4d48d1ec18cd88c046f889ff3da6ce7915554a88493d597de59cda31b49707d8",
    "payment_method_id" : "CREDIT_CARD",
    "payment_card" : 
    {
      "card_type" : "Visa",
      "expiration_month" : 12,
      "expiration_year" : 2018,
      "holder" : "Jeff Lebowski",
      "masked_number" : "************1111",
    },
    "amount" : 0.00
  }],
  "product_items":[{
    "product_id":"123",
    "item_text": "Colored T-Shirt",
    "quantity":2.00,
    "product_name":"Colored T-Shirt",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Black T-Shirt",
    "quantity":1.00,
    "product_name":"Black T-Shirt",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "https://example.com/dw/shop/v15_6/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":"15.6",
  "_type":"fault",
  "fault":{
    "type":"NotFoundException",
    "message":"No order with number '1234567890' 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:

Url

POST https://hostname:port/dw/shop/v15_6/orders/{order_no}/payment_instruments

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

OrderPaymentInstrumentRequest

Response Document

Order

Path Parameters

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

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 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 NotFoundException   Indicates that the order with the given order number is unknown or 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.afterPostPaymentInstrument

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

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

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

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

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

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be added to the basket
Returns:
a non-null Status ends the hook execution
dw.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:
POST /shop/v15_6/orders/00000027/payment_instruments
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
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 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "15.6",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "etag" : "175c697bbfd2f33c9fc88c3469d9a7892ed1821cd2293cf2f91457415e614e24",
         "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" : "OCAPI_Payment_Simple",
         "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:

Url

PATCH https://hostname:port/dw/shop/v15_6/orders/{order_no}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

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

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPaymentMethodIdException

paymentMethodId (String)

Indicates that the provided payment method is invalid or not applicable.
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.afterPatchPaymentInstrument

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

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

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

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

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

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be updated
newPaymentInstrument - the new payment instrument data
Returns:
a non-null Status ends the hook execution
dw.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/v15_6/orders/00000021/payment_instruments/cdZnraOu6bcqwaaadlW5ROJu9Y
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
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 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "15.6",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "etag" : "175c697bbfd2f33c9fc88c3469d9a7892ed1821cd2293cf2f91457415e614e24",
         "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" : "OCAPI_Payment_Simple",
         "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/v15_6/orders/{order_no}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

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

Header Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.

Sample

REQUEST:
DELETE /shop/v15_6/orders/00000029/payment_instruments/cdXTraOu6bXT6aaadll5tOJvce
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "15.6",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
        ...
      }
   ],
...
}