Orders Resource (Shop API 15.2)

Summary

Http Method Resource Description
GET /Orders Get list of customer orders made by a registered customer, filtered by order status and date range.
GET /Orders/{Order_no} Get a customer order identified by the specified order number.
POST /Orders/{Order_no}/Payment_authorize

This resource allows to perform an order payment authorization. No system logic is performed, instead customization is needed to enrich the resource with the logic to authorize the desired payment methods. The resource MAY consume an OrderPaymentInstrumentRequest document and just calls the server side extension points:

  • dw.ocapi.shop.order.beforePaymentAuthorize
  • dw.ocapi.shop.order.afterPaymentAuthorize

No further system logic is performed.

This resource is meant to support more complex payment methods like credit cards. Credit card payments are governed by PCI-DSS, which forbids that information like the credit card security number are persisted on any server. So, client applications that support credit card payments might call this resource to pass the consumer credit card information including the card security number to the Salesforce B2C Commerce server side extension points, which itself might perform a call to a 3rd party payment provider to authorize the payment. In case of a successful authorization the 3rd party payment provider responds the payment transaction id and mightbe additional information which are persisted as a B2C Commerce OrderPaymentInstrument. Finally the extension point logic might switch the order status to 'placed'.

Get Customer Orders

Get list of customer orders made by a registered customer, filtered by order status and date range.

Url

GET https://hostname:port/dw/shop/v15_2/orders?start={Integer}&count={Integer}&from={String}&until={String}&status={String}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

OrderResult

Query Parameters

Parameter Type Description Constraints
count Integer The maximum number of instances per request. Default value is 25. maxIntegerValue=200, minIntegerValue=1
from String The from date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).  
start Integer The result set index to return the first instance for. Default value is 0. minIntegerValue=0
status String The order status of the orders to be retrieved. Status included: created, new, open, completed, cancelled, replaced, failed.  
until String The until date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOrderStatusException   Thrown if specified status is unknown.

Sample

REQUEST:
GET /dw/shop/v15_2/orders?status=created&start=2&count=4 HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
   "_v" : "15.2",
   "count" : 4,
   "data" : [{
      "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_2/promotions/10_bugs_off",
        "item_text": "10$ off",
        "price": -10.00
      }],
      "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
      "order_total":101.00,
      "payment_instruments" : [
      {
        "uuid" : "ce6QR9aaabmakaaadf1KdLcXoH",
        "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" : 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/v15_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
      },
      
      ...

   ],
   "next" : "https://example.com/dw/shop/v15_2/orders?count=4&status=created&start=6",
   "previous" : "https://example.com/dw/shop/v15_2/orders?count=4&status=created&start=0",
   "start" : 2,
   "status" : "created",
   "total" : 8
}


REQUEST:
GET /dw/shop/v15_2/orders?from=2014-06-05T00:00Z&until=2014-06-19T12:30Z&status=created&start=5&count=3 HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
   "_v" : "15.2",
   "count" : 3,
   "data" : [{
      "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_2/promotions/10_bugs_off",
        "item_text": "10$ off",
        "price": -10.00
      }],
      "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
      "order_total":101.00,
      "payment_instruments" : [
      {
        "uuid" : "ce6QR9aaabmakaaadf1KdLcXoH",
        "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" : 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/v15_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
      },
      
      ...
   ],
   "from" : "2014-06-05T00:00Z",
   "next" : "https://example.com/dw/shop/v15_2/orders?count=3&status=created&start=8&from=2014-06-05T00:00Z&until=2014-06-19T12:30Z",
   "previous" : "https://example.com/dw/shop/v15_2/orders?count=3&status=created&start=2&from=2014-06-05T00:00Z&until=2014-06-19T12:30Z",
   "start" : 5,
   "status" : "created",
   "total" : 21,
   "until" : "2014-06-19T12:30Z"
}

Get Order by ID

Get a customer order identified by the specified order number.

Url

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

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String The order number to get the order for. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown in case the order could not be found or didn't belong to the current customer.

Sample

REQUEST:
GET /dw/shop/v15_2/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.2",
  "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_2/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
  "payment_instruments" : [
  {
    "uuid" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "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" : 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/v15_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 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.2",
  "fault":{
    "type":"NotFoundException",
    "message":"No order with number '1234567890' found."
  }
}

Authorize Order Payment

This resource allows to perform an order payment authorization. No system logic is performed, instead customization is needed to enrich the resource with the logic to authorize the desired payment methods. The resource MAY consume an OrderPaymentInstrumentRequest document and just calls the server side extension points:

No further system logic is performed.

This resource is meant to support more complex payment methods like credit cards. Credit card payments are governed by PCI-DSS, which forbids that information like the credit card security number are persisted on any server. So, client applications that support credit card payments might call this resource to pass the consumer credit card information including the card security number to the B2C Commerce server side extension points, which itself might perform a call to a 3rd party payment provider to authorize the payment. In case of a successful authorization the 3rd party payment provider responds the payment transaction id and mightbe additional information which are persisted as a B2C Commerce OrderPaymentInstrument. Finally the extension point logic might switch the order status to 'placed'.

Url

POST https://hostname:port/dw/shop/v15_2/orders/{order_no}/payment_authorize

Formats

json, xml

Authentication

Name Description
None No authentication.

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
x-dw-order-token String the token to authorize order access nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPaymentMethodException

paymentMethodId (String)

Thrown if the requested payment method is unknown or not applicable.
401 UnauthorizedOrderAccessException

orderNo (String)

orderToken (String)

Indicates that the token of the order with the given order number does match the given token.
404 NotFoundException   Indicates that there does no order with the given order number exist.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.afterPaymentAuthorize

afterPaymentAuthorize (order : Order , paymentInstrument : OrderPaymentInstrumentRequest ) : Status

The function is called at last step with in the payment authorization process with the order and a payment instrument, which is optional (so might be null).

Parameters:
order - the order
paymentInstrument - the optional payment instrument
Returns:
  • Status.OK for success.
  • Status.ERROR in case something went wrong.
dw.ocapi.shop.order.beforePaymentAuthorize

beforePaymentAuthorize (order : Order , paymentInstrument : OrderPaymentInstrumentRequest ) : Status

The function is called at first step with in the payment authorization process with the order and a payment instrument, which is optional (so might be null).

Parameters:
order - the order
paymentInstrument - the optional payment instrument
Returns:
  • Status.OK for success.
  • Status.ERROR in case something went wrong.

Sample

REQUEST:
POST /dw/shop/v15_2/orders/1234567890/authorize_payment HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8
x-dw-order-token=8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6

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

# 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.2",
  "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_2/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
 "payment_instruments" : [
  {
    "uuid" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "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
  }],
  "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/v15_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 401 UNAUTHORIZED
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.2",
  "fault":{
    "type":"UnauthorizedOrderAccessException",
    "message":"Unauthorized access to order '1234567890' for token '8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6'."
  }
}