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

Sites resource (Data API 23.2)

Summary

Http Method Resource Description
GET /sites Action to get all existing sites.
GET /sites/{site_id} Action to read an existing site.
GET /sites/{site_id}/ab_tests Action to get all the A/B tests with searching.
GET /sites/{site_id}/ai/recommender_names Get a list of available AI recommenders. Recommenders are configured in the Einstein configurator and are required with AI recommendation API requests.
PUT /sites/{site_id}/cartridges Overwrite cartridge path.
POST /sites/{site_id}/cartridges Add a cartridge to current cartridge path.
DELETE /sites/{site_id}/cartridges/{cartridge_name} Remove a cartridge from cartridge path.
GET /sites/{site_id}/custom_objects/{object_type}/{key} Reads a site specific Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.
PUT /sites/{site_id}/custom_objects/{object_type}/{key} Creates a site specific Custom Object from request body for the specified site. Note that an existing Custom Object for the site, with the same key, will be overwritten by this action.
DELETE /sites/{site_id}/custom_objects/{object_type}/{key} Deletes a site specific Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.
PATCH /sites/{site_id}/custom_objects/{object_type}/{key} Updates a site specific Custom Object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.
GET /sites/{site_id}/locale_info/locales Action to get the set of locales with the system given a site.
PATCH /sites/{site_id}/orders/{order_no} Updates the order.
PUT /sites/{site_id}/orders/{order_no}/confirmation_status Updates the order confirmation status.
PUT /sites/{site_id}/orders/{order_no}/export_status Updates the order export status. Setting the status to EXPORTED will also trigger the finalization of on-order inventory transactions for this order, meaning that all inventory transactions with type on-order will be moved into final inventory transactions. This is only relevant when on-order inventory is turned on for the inventory list ordered products are in.
PUT /sites/{site_id}/orders/{order_no}/external_status Updates the order external status.
PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id} Updates the payment instrument of an order.
PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}/transaction Updates the transaction of an order payment instrument.
PUT /sites/{site_id}/orders/{order_no}/payment_status Updates the order payment status.
PUT /sites/{site_id}/orders/{order_no}/shipments/{shipment_id}/shipping_address Updates (create or replace) the order shipment address.
PUT /sites/{site_id}/orders/{order_no}/shipping_status Updates the order shipping status.
PUT /sites/{site_id}/orders/{order_no}/status Updates the order status by using the corresponding methods (fail, undoFail, place, cancel and undoCancel) from the dw.order.OrderMgr. Orders which are not in status CREATED or FAILED can not be set back.
GET /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type} For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
PATCH /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type} For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "************" since it is a reserved value.
GET /sites/{site_id}/slot_configurations Action to get all the slot configurations with no filtering.

Get Sites

Action to get all existing sites.

Url

GET https://hostname:port/dw/data/v23_2/sites?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Sites

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/sites?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "23.2",
  "count" : 2,
  "data" : [ 
    {
        "_v" : "23.2",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "SiteGenesis",
            "link" : "https://example.com/s/-/dw/data/v23_2/customer_lists/SiteGenesis"
        },
        "description" : {
            "default": "Prototypical site used for starting point",
        }
        "display_name" : {
            "default": "Site Genesis",
        }
        "id" : "SiteGenesis",
        "in_deletion": false,
        "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis",
        "storefront_status": "online"
    },
    {
        "_v" : "23.2",
        "_type" : "site",
        "customer_list_link" : {
            "_type" : "customer_list_link",
            "customer_list_id" : "MyCustomerList",
            "link" : "https://example.com/s/-/dw/data/v23_2/customer_lists/MyCustomerList"
        },
        "description" : {
            "default": "A site that sells products",
        }
        "display_name" : {
            "default": "My Site",
        }
        "id" : "MySite",
        "in_deletion": false,
        "link" : "https://example.com/s/-/dw/data/v23_2/sites/MySite",
        "storefront_status": "online"
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 2
}

Get site

Action to read an existing site.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Site

Path Parameters

Parameter Type Description Constraints
site_id String the id of the site minLength=1

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis HTTP/1.1
Host: example.com
Authorization:Bearer ac734607-c966-44fb-8739-8ea413a2c0a5
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "site",
   "customer_list_link" : 
   {
      "_type" : "customer_list_link",
      "customer_list_id" : "SiteGenesis",
      "link" : "https://example.com/s/-/dw/data/v23_2/customer_lists/SiteGenesis"
   },
   "description" : "Site's site used for WAPI integration test.",
   "id" : "SiteGenesis"
}

# in case of failure (SecureCommunicationRequired, i.e. no http):

RESPONSE:
HTTP/1.1 403 Forbidden
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" : 
   {
      "type" : "SecureCommunicationRequiredException",
      "message" : "A secure connection is required."
   }
}

# in case of failure (SiteNotFound, i.e. invalid site id):

RESPONSE:
HTTP/1.1 404 Forbidden
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" : 
   {
      "type" : "SiteNotFoundException",
      "message" : "No site with ID 'foobar' was found."
   }
}

Get AB/Tests

Action to get all the A/B tests with searching.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/ab_tests?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

AbTests

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site that the A/B tests are contained within. mandatory=true, maxLength=256, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25). minIntegerValue=0
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0). minIntegerValue=0

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/ab_tests?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json

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

{
  "_v" : "23.2",
  "_type" : "ab_test_search_result",
  "count" : 2,
  "data" : [
    {
       "_v" : "23.2",
       "_type" : "ab_tests",
       "_resource_state":"c2309jd239jdrifj3ui4fn",
       "customer_groups" : 
       [
          "abtest_customer_group"
       ],
       "description" : "my abtest1 description",
       "email_addresses" : 
       [
          "[email protected]"
       ],
       "enabled" : true,
       "end_date" : "2015-07-31T23:09:08.000Z",
       "expiration_type" : "session",
       "id" : "my-abtest1",
       "key_metric_id" : "abtest_key_metric_id",
       "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/ab_tests/my-abtest1",
       "paused" : true,
       "start_date" : "2015-04-01T11:30:15.000Z",
       "tags" : 
       [
          "abtest_tag"
       ],
       "test_groups" : 
       [
          {
             "_type" : "ab_test_group",
             "allocation" : 20,
             "custom_experience" : false,
             "id" : "Control"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 40,
             "custom_experience" : false,
             "description" : "A description",
             "id" : "Test Segment A"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 40,
             "custom_experience" : false,
             "id" : "Test Segment B"
          }
       ],   
       "trigger" : 
       {
          "_type" : "ab_test_trigger",
          "is_pipeline_based" : false,
          "trigger_type" : "immediately"
       }    
    },
    {
       "_v" : "23.2",
       "_type" : "ab_test",
       "_resource_state":"9g9jrfc93jr03fr09sdcjk",
       "customer_groups" : 
       [
          "abtest_customer_group"
       ],
       "description" : "my abtest2 description",
       "email_addresses" : 
       [
          "[email protected]"
       ],
       "enabled" : true,
       "end_date" : "2015-07-31T23:09:08.000Z",
       "expiration_type" : "session",
       "id" : "my-abtest2",
       "key_metric_id" : "abtest_key_metric_id",
       "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/ab_tests/my-abtest2",
       "paused" : true,
       "start_date" : "2015-04-01T11:30:15.000Z",
       "tags" : 
       [
          "abtest_tag"
       ],
       "test_groups" : 
       [
          {
             "_type" : "ab_test_group",
             "allocation" : 20,
             "custom_experience" : false,
             "id" : "Control"
          },
          {
             "_type" : "ab_test_group",
             "allocation" : 80,
             "custom_experience" : false,
             "id" : "Test Segment B"
          }
       ],   
       "trigger" : 
       {
          "_type" : "ab_test_trigger",
          "is_pipeline_based" : true,
          "trigger_type" : "pipeline_call",
          "pipeline_calls" :
          [
              "My-Pipeline"
          ]
       }
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 2
}

Get recommenders

Get a list of available AI recommenders. Recommenders are configured in the Einstein configurator and are required with AI recommendation API requests.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/ai/recommender_names

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

RecommendersResult

Path Parameters

Parameter Type Description Constraints
site_id String Site ID to get a list of recommenders for. mandatory=true, maxLength=256, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CQuotientException

originalStatusCode (Integer)

responseBody (String)

 If CQuotient responds with a non-success status code.
404 SiteNotFoundException

siteId (String)

 If the given site does not exist.

Sample

REQUEST:
GET /dw/data/v23_2/sites/SiteGenesis/ai/recommender_names HTTP/1.1
Host: example.com
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json

# in case of success

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

{
  "_v" : "23.2",
  "_type": "recommenders_result",
  "recommenders": [
    {
      "_type": "recommender",
      "description": "Recommender for Alternate Products on a PDP",
      "name": "Alternate-Product-to-Product"
    },
    {
      "_type": "recommender",
      "description": "** for shared demo **",
      "name": "topsellers"
    },
    {
      "_type": "recommender",
      "description": "Shopper, Recently-Viewed",
      "name": "recently-viewed"
    },
    {
      "_type": "recommender",
      "description": "demo",
      "name": "demo"
    }
  ]
}

# in case of failure

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

{
  "_v" : "23.2",
  "fault": {
    "arguments": {
      "siteId": "UnknownSite"
    },
    "type": "SiteNotFoundException",
    "message": "No site with ID 'UnknownSite' was found."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 57

{
  "_v" : "23.2",
  "fault": {
    "arguments": {
      "originalStatusCode": "400",
      "responseBody": "{\"code\":\"1\",\"message\":\"The given site id is not valid\"}"
    },
    "type": "CQuotientException",
    "message": "Proxy error ('400'): '{"code":"1","message":"The given site id is not valid"}'."
  }
}

Overwrite cartridge path

Overwrite cartridge path.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/cartridges

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CartridgePathCreateRequest

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCartridgePathException

targetCartridge (String)

 Indicates that the cartridge path is invalid
404 SiteNotFoundException

siteId (String)

 Indicates that site specified with the given id is unknown.

Sample

Request
PUT /s/-/dw/data/v23_2/sites/{site-id}/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache
{
    "cartridges": "new_cartridges1:new_cartridges2"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v" : "23.2",
    "_type": "cartridge_path_api_response",
    "cartridge_path": "new_cartridges1:new_cartridges2:core",
    "site_id": "SiteGenesis"
}

# in case of failure when site not found
RESPONSE:
HTTP/1.1 404
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "siteId": "unknownSite"
        },
        "type": "SiteNotFoundException",
        "message": "No site with ID 'SiteGenesis1' was found."
    }
}

# in case of failure when site not found
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "cartridge": "1BadCartidgeName:2BadCartidgeName"
        },
        "type": "InvalidCartridgePathException",
        "message": "Invalid cartridge path '1BadCartidgeName:2BadCartidgeName'. Cartridge names may only contain letters, numbers, or \"_\", must start with a letter, and be separated by \":\". "
    }
}

Add a cartridge to cartridge path

Add a cartridge to current cartridge path.

Url

POST https://hostname:port/dw/data/v23_2/sites/{site_id}/cartridges

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CartridgePathAddRequest

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOperationException

targetCartridge (String)

 The error may happen when position is either 'after' or 'before'. It indicates either target cartridge is not a existing custom cartridge.
400 CartridgeAlreadyExistException

targetCartridge (String)

 Indicates that the cartridge already exist in cartridge path
400 InvalidCartridgeException

targetCartridge (String)

 Indicates that the cartridge name is invalid
404 SiteNotFoundException

siteId (String)

 Indicates that site specified with the given id is unknown.

Sample

Request

# Example 1: Add to first

POST /s/-/dw/data/v23_2/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "first"
}

# Example 2: Add to last
POST /s/-/dw/data/v23_2/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "last"
}

# Example 3: Add Before
POST /s/-/dw/data/v23_2/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "before",
    "target" : "custom_cartridge_1"
}


# Example 4: Add After
POST /s/-/dw/data/v23_2/sites/SiteGenesis/cartridges HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

{
    "name": "new_cartridge",
    "position": "after",
    "target" : "custom_cartridge_1"
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v" : "23.2",
    "_type": "cartridge_path_api_response",
    "cartridges": "new_cartridge:custom_cartridge_1:custom_cartridge_2:core",
    "site_id": "SiteGenesis"
}

# in case of failure when site not found:
RESPONSE:
HTTP/1.1 404
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "siteId": "unknownSite"
        },
        "type": "SiteNotFoundException",
        "message": "No site with ID 'SiteGenesis1' was found."
    }
}


# in case of failure when cartridge already exist:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "cartridge": "new_cartridge"
        },
        "type": "CartridgeAlreadyExistException",
        "message": "Cartridge 'new_cartridge' already exists."
    }
}

# in case of failure when cartridge is invalid:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "cartridge": "123test"
        },
        "type": "InvalidCartridgeException",
        "message": "Invalid cartridge '123test'. Cartridge names may only contain letters, numbers, or \"_\", must start with a letter."
    }
}

# in case of failure when target cartridge is invalid
# Target cartridge is invalid when
# 1. target cartridge is null 2. target cartridge is a system cartridge 3. target cartridge doesn't exist
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "target_cartridge": "core"
        },
        "type": "InvalidOperationException",
        "message": "Invalid operation on cartridge 'core'. The operation is only allowed on existing custom cartridge."
    }
}

Remove a cartridge from cartridge path

Remove a cartridge from cartridge path.

Url

DELETE https://hostname:port/dw/data/v23_2/sites/{site_id}/cartridges/{cartridge_name}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CartridgePathApiResponse

Path Parameters

Parameter Type Description Constraints
cartridge_name String request body mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOperationException

targetCartridge (String)

 It indicates either the cartridge doesn't exist in cartridge path or the cartridge can not be deleted (e.g. System Cartridge).
404 SiteNotFoundException

siteId (String)

 Indicates that site specified with the given id is unknown.

Sample

Request
DELETE /s/-/dw/data/v23_2/sites/SiteGenesis/cartridges/customer_cartridge_2 HTTP/1.1
Host: {host}
Content-Type: application/json
Authorization: {access_token}
Cache-Control: no-cache

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
    "_v" : "23.2",
    "_type": "cartridge_path_api_response",
    "cartridges": "custom_cartridge_1:custom_cartridge_3:core",
    "site_id": "SiteGenesis"
}

# in case of failure:
RESPONSE:
HTTP/1.1 400
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
    "_v" : "23.2",
    "fault": {
        "arguments": {
            "target_cartridge": "core"
        },
        "type": "InvalidOperationException",
        "message": "Invalid operation on cartridge 'core'. The operation is only allowed on existing custom cartridge."
    }
}

Read site specific Custom Object

Reads a site specific Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

 If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

 For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

 For an unknown object type ID

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "custom_object",
   "object_type":"my_object_type",
   "key_property":"key_attribute",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# 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",
  "fault":
  {
    "type":"CustomObjectNotFoundException",
    "message":"No custom object with key 'key_0815' for object type 'my_object_type' was found.
  }
}

Create site specific Custom Object

Creates a site specific Custom Object from request body for the specified site. Note that an existing Custom Object for the site, with the same key, will be overwritten by this action.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomObject

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

 If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

 For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

 For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforePut

beforePut (create : CustomObject ) : Status

The function is called before the custom object is created with create document.

Parameters:
create - the create document, may be null
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterPut

afterPut (customObject : CustomObject , create : CustomObject ) : Status

The function is called after the custom object was created with create document.

Parameters:
customObject - the created custom object
create - the create document, may be null
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PUT /s/-/dw/data/v23_2/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Location: https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/custom_objects/my_object_type/key_0815
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
  "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
  "_type" : "custom_object",
  "object_type":"my_object_type",
  "key_property":"key_attribute",
  "key_value_string":"key_0815",
  "c_boolean":true,
  "c_date":"2015-02-03T00:00:00.000Z",
  "c_email":"[email protected]",
  "c_integer":42,
  "c_number":42.0,
  "c_string":"some text"
}

# 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",
  "fault":
  {
    "type":"ObjectTypeNotFoundException",
    "message":"No object type with ID 'my_object_type' was found."
  }
}

Delete site specific Custom Object

Deletes a site specific Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.

Url

DELETE https://hostname:port/dw/data/v23_2/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

 If the object key must be an integer, but the path parameter has an invalid format
404 ObjectTypeNotFoundException

objectType (String)

 For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforeDelete

beforeDelete (customObject : CustomObject ) : Status

The function is called before the custom object is removed.

Parameters:
create - the create document
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterDelete

afterDelete () : Status

The function is called after the custom object was deleted.

Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:

RESPONSE:
HTTP/1.1 204 OK

# 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",
  "fault":
  {
    "type":"ObjectTypeNotFoundException",
    "message":"No object type with ID 'my_object_type' was found."
  }
}

Update site specific Custom Object

Updates a site specific Custom Object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/custom_objects/{object_type}/{key}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomObject

Response Document

CustomObject

Path Parameters

Parameter Type Description Constraints
key String the key attribute value of the Custom Object mandatory=true, minLength=1, nullable=false
object_type String the ID of the object type mandatory=true, minLength=1, nullable=false
site_id String the ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedKeyParameterException

value (String)

parameter (String)

 If the object key must be an integer, but the path parameter has an invalid format
404 CustomObjectNotFoundException

key (String)

objectType (String)

 For an unknown object key
404 ObjectTypeNotFoundException

objectType (String)

 For an unknown object type ID

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.data.object.beforePatch

beforePatch (customObject : CustomObject , update : CustomObject ) : Status

The function is called before the custom object is updated with update document.

Parameters:
update - the update document
Returns:
a non-null Status ends the hook execution
dw.ocapi.data.object.afterPatch

afterPatch (customObject : CustomObject , create : CustomObject ) : Status

The function is called after the custom object was updated with update document.

Parameters:
customObject - the updated custom object
update - the update document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/sites/SiteGenesis/custom_objects/my_object_type/key_0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
   "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "custom_object",
   "object_type":"my_object_type",
   "key_property":"key_attribute",
   "c_boolean":true,
   "c_date":"2015-02-03T00:00:00.000Z",
   "c_email":"[email protected]",
   "c_integer":42,
   "c_number":42.0,
   "c_string":"some text"
}

# 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",
  "fault":
  {
    "type":"CustomObjectNotFoundException",
    "message":"No custom object with key 'key_0815' for object type 'my_object_type' was found.
  }
}

Get Locales for given Site

Action to get the set of locales with the system given a site.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/locale_info/locales?include_all={Boolean}&id={String}&select={String}&start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

LocaleResult

Path Parameters

Parameter Type Description Constraints
site_id String Only locales specified for the site are returned minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer the count of the records to return in this page. Default is 25.  
id String optional locale to return by id. If specified, that locale is looked up and returned, otherwise the list is returned.  
include_all Boolean true if we want to include all the locales. Default is false.  
select String the set of fields to return from the request. Default is only the locale id.  
start Integer the start index for paging. Default is 0.  

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/locale_info/locales?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

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",
   "_type" : "locale_result",
   "count" : 4,
   "hits" :
   [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : true,
         "display_country" : "",
         "display_language" : "",
         "display_name" : "default",
         "id" : "default",
         "iso3_country" : "",
         "iso3_language" : "",
         "language" : "",
         "name" : "default"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "español",
         "display_name" : "español",
         "id" : "es",
         "iso3_country" : "",
         "iso3_language" : "spa",
         "language" : "es",
         "name" : "Spanish"
      }
   ],
   "select" : "(**)",
   "start" : 0,
   "total" : 4
}

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/locale_info/locales?include_all=true&select=(**)&start=3&count=8 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

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",
   "_type" : "locale_result",
   "count" : 8,
   "hits" : [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : true,
         "display_country" : "",
         "display_language" : "",
         "display_name" : "default",
         "id" : "default",
         "iso3_country" : "",
         "iso3_language" : "",
         "language" : "",
         "name" : "default"
      },
      {
         "_type" : "locale",
         "active" : false,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "Nederlands",
         "display_name" : "Nederlands",
         "id" : "nl",
         "iso3_country" : "",
         "iso3_language" : "nld",
         "language" : "nl",
         "name" : "Dutch"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "",
         "default" : false,
         "display_country" : "",
         "display_language" : "English",
         "display_name" : "English",
         "id" : "en",
         "iso3_country" : "",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English"
      },
      {
         "_type" : "locale",
         "active" : false,
         "country" : "CA",
         "default" : false,
         "display_country" : "Canada",
         "display_language" : "English",
         "display_name" : "English (Canada)",
         "id" : "en-CA",
         "iso3_country" : "CAN",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (Canada)"
      },
      {
         "_type" : "locale",
         "active" : true,
         "country" : "US",
         "default" : false,
         "display_country" : "United States",
         "display_language" : "English",
         "display_name" : "English (United States)",
         "id" : "en-US",
         "iso3_country" : "USA",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (United States)"
      }
   ],
   "include_all": true,
   "select" : "(**)",
   "start" : 0,
   "total" : 8
}

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/locale_info/locales?id=en-US&select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

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",
   "_type" : "locale_result",
   "count" : 1,
   "hits" : [
      {
         "_type" : "locale",
         "active" : true,
         "country" : "US",
         "default" : false,
         "display_country" : "United States",
         "display_language" : "English",
         "display_name" : "English (United States)",
         "id" : "en-US",
         "iso3_country" : "USA",
         "iso3_language" : "eng",
         "language" : "en",
         "name" : "English (United States)"
      }
   ],
   "id": "en-US",
   "select" : "(**)",
   "start" : 0,
   "total" : 1
}

Updates the order

Updates the order.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PATCH  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "c_strValue": "string value",
    "c_intValue": 1,
    "c_textValue": "text value",
    "c_dateTimeValue": "2019-10-07",
    "c_strValue2": null
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order confirmation status

Updates the order confirmation status.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/confirmation_status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderConfirmationStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/confirmation_status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "confirmed"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order export status

Updates the order export status. Setting the status to EXPORTED will also trigger the finalization of on-order inventory transactions for this order, meaning that all inventory transactions with type on-order will be moved into final inventory transactions. This is only relevant when on-order inventory is turned on for the inventory list ordered products are in.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/export_status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderExportStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/export_status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "exported"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order external status

Updates the order external status.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/external_status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderExternalStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/external_status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "external status"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the payment instrument of an order

Updates the payment instrument of an order.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

PaymentInstrumentUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
payment_instrument_id String ID of the payment instrument mandatory=true, minLength=1, nullable=false
site_id String ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

 In case of the given payment_instrument_id does not reference an existing payment instrument.

Sample

REQUEST:
PATCH  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/payment_instruments/d98550eb1e1cf6db15dd655a9e HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "c_strValue": "string value",
    "c_intValue": 1,
    "c_textValue": "text value",
    "c_dateTimeValue": "2019-10-07",
    "c_strValue2": null
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"PaymentInstrumentNotFoundException",
    "message":"The payment instrument with ID 'd98550eb1e1cf6db15dd655a9e' couldn't be found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the transaction of an order payment instrument

Updates the transaction of an order payment instrument.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}/transaction

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

PaymentTransactionUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
payment_instrument_id String ID of the payment instrument mandatory=true, minLength=1, nullable=false
site_id String ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

 In case of the given payment_instrument_id does not reference an existing payment instrument.
404 PaymentTransactionNotFoundException

paymentInstrumentId (String)

 In case of the payment instrument does not reference a payment transaction.

Sample

REQUEST:
PATCH  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/payment_instruments/d98550eb1e1cf6db15dd655a9e/transaction HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "c_strValue": "string value",
    "c_intValue": 1,
    "c_textValue": "text value",
    "c_dateTimeValue": "2019-10-07",
    "c_strValue2": null
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"PaymentInstrumentNotFoundException",
    "message":"The payment instrument with ID 'd98550eb1e1cf6db15dd655a9e' couldn't be found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"PaymentTransactionNotFoundException",
    "message":"The payment transaction of the payment instrument with ID 'd98550eb1e1cf6db15dd655a9e' couldn't be found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order payment status

Updates the order payment status.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/payment_status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderPaymentStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/payment_status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "paid"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates (create or replace) the order shipment address

Updates (create or replace) the order shipment address.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/shipments/{shipment_id}/shipping_address

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

ShippingAddressUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
shipment_id String ID of the shipment mandatory=true, minLength=1, nullable=false
site_id String ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.
404 ShipmentNotFoundException

shipmentId (String)

 In case of the given shipment_id does not reference an existing shipment.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/shipments/express_shipment/shipping_address HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "address1":"10 Presidential Way",
    "address2":"10 Presidential Way 2",
    "city":"Woburn",
    "last_name":"Lastname",
    "title":"Prof. Dr.",
    "country_code":"US",
    "phone":"+49 123 456789",
    "company_name":"COMPANY",
    "second_name":"Secondname",
    "salutation":"Mr.",
    "state_code":"MA",
    "postal_code":"01801",
    "first_name":"Firstname",
    "job_title":"Director",
    "c_strValue": "string value",
    "c_intValue": 1,
    "c_textValue": "text value",
    "c_dateTimeValue": "2019-10-07",
    "c_strValue2": null
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"ShipmentNotFoundException",
    "message":"No shipment with ID 'express_shipment' could be found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order shipping status

Updates the order shipping status.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/shipping_status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderShippingStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site. mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/shipping_status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "shipped"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

Updates the order status

Updates the order status by using the corresponding methods (fail, undoFail, place, cancel and undoCancel) from the dw.order.OrderMgr. Orders which are not in status CREATED or FAILED can not be set back.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/orders/{order_no}/status

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

OrderStatusUpdateRequest

Path Parameters

Parameter Type Description Constraints
order_no String The order number mandatory=true, minLength=1, nullable=false
site_id String ID of the site mandatory=true, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

 In case of the given order_no does not reference an existing order.
404 SiteNotFoundException

siteId (String)

 In case of the given site_id does not reference an existing site.
409 OrderStatusTransitionException

orderNumber (String)

fromStatus (String)

toStatus (String)

 The status change is not supported.
409 OrderPreviouslyIntegratedStatusException

orderNumber (String)

fromStatus (String)

toStatus (String)

 The status change is not supported. The order was previously integrated with an external order management system which has responsibility for further status changes.
409 OrderIntegrationStatusException

orderNumber (String)

fromStatus (String)

toStatus (String)

 The status change is not supported. An external order management system is integrated which has responsibility for further status changes on placed orders.
409 CancelOrderException

orderNumber (String)

 The order could not be cancelled.
409 PlaceOrderException

orderNumber (String)

 The order could not be placed.
409 UndoCancelOrderException

orderNumber (String)

 The cancelled order can not be reopened.
409 UndoFailOrderException

orderNumber (String)

 The failed order can not be reopened.

Sample

REQUEST:
PUT  https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/orders/12345/status HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "status": "created"
}

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderNotFoundException",
    "message":"No order with number '12345' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"SiteNotFoundException",
    "message":"No site with ID 'SiteGenesis' could be found."
  }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"OrderStatusTransitionException",
    "message":"The order status change from 'NEW' to 'CREATED' for order with number '12345' is not supported."
  }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"PlaceOrderException",
    "message":"Order with number '12345' cannot be placed."
  }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"CancelOrderException",
    "message":"Order with number '12345' cannot be cancelled."
  }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"UndoCancelOrderException",
    "message":"The cancelled order with number '12345' cannot be reopened."
  }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
  "_v":"23.2",
  "fault":{
    "type":"UndoFailOrderException",
    "message":"The failed order with number '12345' cannot be reopened."
  }
}

Get Custom Site Preferences

For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

SitePreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String One of {staging,development,sandbox,production,current}.  
site_id String The site context. minLength=1

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean Set to true to mask the values of preferences of type Password.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

 Indicates the preference group is not found.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging?expand=sites HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "23.2",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis",
    "storefront_status" : "online"
   },
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}

Update Custom Site Preferences

For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "************" since it is a reserved value.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SitePreferences

Response Document

SitePreferences

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String One of {staging,development,sandbox,production}.  
site_id String The site context. minLength=1

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean Set to true to mask the values of preferences of type Password.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

 Indicates the preference group is not found.
404 ObjectTypeNotFoundException

objectType (String)

 Indicates the SitePreferences system object is not found.

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "23.2",
   "_type" : "preferences",
   "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/site_preferences/preference_groups/my-preferencegroup/staging",
   "site" : 
   {
    "_type" : "site",
    "id" : "SiteGenesis",
    "in_deletion" : false,
    "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis",
    "storefront_status" : "online"
   },
   "c_preference1" : "Teal",
   "c_preference2" : 
   [
      "Small",
      "Large"
   ],
   "c_preference3" : false,
   "c_preference4" : 20
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CustomPreferenceGroupNotFoundException",
    "message":"No preference group with ID 'my-preferencegroup' was found."
  }
}

Get Slot Configurations

Action to get all the slot configurations with no filtering.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/slot_configurations?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

SlotConfigurations

Path Parameters

Parameter Type Description Constraints
site_id String The id of the site. minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/sites/SiteGenesis/slot_configurations?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "23.2",
  "count" : 2,
  "data" : [
    {
        "_v" : "23.2",
       "_type" : "slot_configuration",
        "slot_id":"header-banner",
        "uuid":"fsdoi43ofijwdf",
        "configuration_id":"2015-06-24_16:33:18",
        "slot_content":
        {
            "type":"html",
            "body":
            {
                "default":"<html>HTML content</html>"
            }
        },
        "customer_groups":[
            "Administrators",
            "Registered"
        ],
        "assigned_to_site" : true,
        "context":"global",
        "enabled":true,
        "default":true,
        "rank":2,
        "description":"slot configuration description",
        "callout_msg":
        {
            "default":"some message"
        },
        "schedule":
        {
            "start_date":"2013-03-28T23:21:00.000Z",
            "end_date":"2022-03-28T23:21:00.000Z",
            "recurrence":
            {
                "day_of_week":[
                    "monday",
                    "sunday"
                ],
                "time_of_day":
                {
                    "time_from":"00:00:00",
                    "time_to":"23:59:00"
                }
            }
        }
    }
  ],
  "select": "**",
  "start" : 0,
  "total" : 1
}

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

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