CartResource

The Carts resource provides read/write access to the shopping carts in InService. Each cart acts as a container to which the user can add or remove parts. Items within a cart can be updated e.g. you can increment the count of items, or add a textual comment. Carts are managed per-user, and a user can have any number of carts. Customizable delegates provide validation, recommendation and business process support such as supersession – these delegates operate on Cart and cart contents. The contents of the cart can be ordered, passing the items through to an order processing delegate which can interface to an external order processing system.

Named Objects & Collections

NameDescription
items The items contained within the cart.
recommended The recommended items based on the contents of the cart.

Action Links

NameDescription
action_update_self The link to update an individual cart.
action_delete_self The link to delete an individual cart.
action_order The link to process the ordering of a cart.
action_create The link to create a cart. (Available on an SCList)
action_update_group The link to update a list of carts. (Available on an SCList)
action_delete_group The link to delete a list of carts. (Available on an SCList)

Data Model Objects

  • SCEShoppingCart
  • SCCartItem

Customization Points

ClassMethodDescription
com.ptc.sc.services.plugins.CommerceDelegate validateRequestedItem The validateRequestedItem method is called on all items that are added to cart. A requested item is the part for which the user has clicked on the "add to cart" button in the UI. If the item is accepted (validated), the cart processing logic will move on to replaceItem (see below). If validation fails, the "add to cart" action fails and a message is returned to the caller.
com.ptc.sc.services.plugins.CommerceDelegate validateActualItem The validateActualItem method is called following replaceItem. A actual item is the part that is actually being added to the cart (could be replaced or could be the same as the requested item). If the item is accepted (validated), the cart processing logic will add the item to cart. If validation fails, the "add to cart" action fails and a message is returned to the caller.
com.ptc.sc.services.plugins.CommerceDelegate validateCart The validateCart method is called prior to ordering, it can also be called at any time through the validate api call. validateCart can check the cart contents as a whole.
com.ptc.sc.services.plugins.CommerceDelegate replaceItem The replaceItem method is called following validateRequestedItem, and can run any business logic to upgrade or alter the chosen object that is being added to the cart. The default OOTB behavior demonstrates automatic supersession, using the supersession business services to provide the latest part. replaceItem can return N number of items for 1 item passed in, supporting 1:N supersession for example.
com.ptc.sc.services.plugins.CommerceDelegate findExistingCartItem When items are added to a cart, the findExistingCartItem method is used to determine if the item already exists in the cart.
com.ptc.sc.services.plugins.RecommendationDelegate getRecommendations The getRecommendations method can return a list of parts which are related to the object that is passed to the delegate. Recommendations can be performed on the contents of a partlist or on the contents of a cart.
com.ptc.sc.services.plugins.RecommendationDelegate isOnline Returns the active status of the recommendations engine.

The following resources are applicable:

POST /carts/remove

Delete a list of given carts.

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) The SCList of carts to be deleted.

Response Codes

code condition
204 Returned if a list of carts were successfully deleted.
400 Returned when the content does not contain data or the cartId of any item in the SCList is not of valid ID format.
404 Returned when none of the carts is found
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/{cartId}/validate

Validates that an order can be generated from the contents of an existing Shopping Cart.

Request Parameters

name type description default
cartId path The id of the shopping cart to create the order from. n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The attributes to use in defining the order.

Response Codes

code condition
200 Returned if the contents of the cart are valid for creating an order
404 Returned if the cart is not found or accessible.
409 Returned if the cart not valid for order creation
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n
500 Returned if the dealer header doesn't match the cart's affiliated dealer or something else goes wrong

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/{cartId}/order

Creates an order from an existing Shopping Cart. The order will be affiliated to the same dealer as the cart.

Request Parameters

name type description default
cartId path The id of the shopping cart to create the order from. n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The attributes to use in defining the order.

Response Codes

code condition
201 Returned when the new order is created.
400 Returned when the cartId is not of valid ID format.
404 Returned if the cart is not found or accessible.
409 Returned if the cart not valid for order creation
415 Returned if the Content-Type is not
500 Returned if the dealer header doesn't match the cart's affiliated dealer or something else goes wrong application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCItem (JSON)

GET /carts/{cartId}/recommendations

Retrieves the recommended parts based on the cart's contents.

Request Parameters

name type description default
cartId path The id of the cart for recommendations n/a
$filter query -- Reserved for future use. -- n/a
$orderby query The OData order by n/a
$skip query The number of items to skip for the start of this page. n/a
$top query The number of objects to return in this page. n/a

Response Codes

code condition
400 Returned when the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID
501 Returned when there is no recommendation delegate in the system.
503 Returned when an external recommendation delegate is offline.

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/sendemail

Sends an email with given data provided by the user.

This takes an SCList of one SCItem containing all of the form input parameters from the Send Email UI. It uses these input parameters to send the email. The cart is send as an attachment with chosen export type.

The UI has the following fields.

NameDescription
exportTypelist of available export types
subjectthe email subject
recipientscomma separated email addresses for recipients
messagethe message for email body

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) an SCList of one SCItem containing all of the form input parameters from the Send Email UI

Response Codes

code condition
200 returned if email was send successfully
400 returned if request data is bad
502 returned if email was NOT successfully send

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)
Available Since
InService 6.0

GET /carts/{cartId}

Retrieves a specific shopping cart by the given shopping cart ID.

Available Since
InService 6.0

Request Parameters

name type description default
cartId path the ID of the shopping cart to retrieve n/a
$expand query the OData expand clause used to expand attribute objects and collections.

To expand the items collection when requesting the shopping cart use: $expand=items

 n/a
$filter query -- Reserved for future use. -- n/a
$orderby query the ordering of cart items when expanding items n/a
$skip query the number of cart items to skip for paging when expanding items n/a
$top query the number of cart items to return in a page when expanding items n/a

Response Codes

code condition
400 returned when the cartId is not of valid ID for a shopping cart
404 returned when a shopping cart is not found for the given cart ID

Response Body

media type data type
application/vnd.ptc.sc+json SCItem (JSON)

GET /carts/shoppingparameters

Retrieves shopping parameters. If none of the query parameters are provided then all the available shopping parameters are returned.

Request Parameters

name type description default
forParamName query The name of the parameter needed to get the values for the requestedParamName. n/a
forParamValue query The value of the above forParamName.
For example, for the scenario where location field values depends on customer field value. If value of location field is needed the below queryparam should be supplied:
requestedParamName=location
forParamName=customer
forParamValue=--value of customer field--		 n/a
requestedParamName query Get the values for this parameter n/a

Response Codes

code condition
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=1.

Response Body

media type data type
application/vnd.ptc.sc+json SCFieldList (JSON)

GET /carts

Retrieves all carts for the given user in all dealerships and unaffiliated carts.

Retrieves all carts with in specific dealerships. For example:

Carts in dealer wt.inf.library.WTLibrary-33096

$filter=dealerReference eq 'wt.inf.library.WTLibrary-33096'

Retrieves all carts that are unaffiliated. For example:

$filter=dealerReference eq 'unaffiliated'

Retrieves all carts in a set of dealerships, including unaffiliated carts. For example:

Carts in dealer wt.inf.library.WTLibrary-33096 and unaffiliated carts

$filter=dealerReference eq 'wt.inf.library.WTLibrary-33096' or dealerReference eq 'unaffiliated'


If the activeCart is not specified no metadata for the active cart will be returned. If the activeCart is specified, the $expand must specify 'activeCart'. For example:

$expand=activeCart

activeCart=com.ptc.sce.cart.SCEShoppingCart-12345

Request Parameters

name type description default
$expand query The OData expand clause, in this case only used to indicate to get active cart metadata. n/a
$filter query Allows filtering by dealer with the format: dealerReference eq 'dealerId' n/a
$orderby query The OData order by n/a
$skip query The number of items to skip for the start of this page. n/a
$top query The number of objects to return in this page. n/a
activeCart query The id of the active cart, whose metadata should be included in the result n/a

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

GET /carts/get_all_ids

Retrieves all cart ids for the given user. This does not return serialized carts, it returns a List of ids.

Response Body

media type data type
application/vnd.ptc.sc+json array of object (JSON)

POST /carts

Creates a list of carts.

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) The SCList of carts to create.

Response Codes

code condition
400 Returned when the content does not contain data.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

PUT /carts/{cartId}

Updates an existing cart.

Request Parameters

name type description default
cartId path The ID of the cart to be updated. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The cart to be updated.

Response Codes

code condition
400 Returned when the content does not contain the correct cart data for the update or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCItem (JSON)

DELETE /carts/{cartId}

Deletes the specified cart.

Request Parameters

name type description default
cartId path The ID of the cart to be deleted. n/a

Response Codes

code condition
204 Returned if the cart was successfully deleted.
400 Returned when a cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

GET /carts/{cartId}/items

Retrieves the cart items of a specific cart. This method validate that cart item parts are in the right parts list context and parts exists in e3c.

Request Parameters

name type description default
cartId path The ID of the cart whose items to retrieve. n/a
$expand query The OData expand parameter. $expand=context is used to inject context path collection to each cart item n/a
$filter query -- Reserved for future use. -- n/a
$orderby query The OData order by n/a
$skip query The number of items to skip for the start of this page. n/a
$top query The number of objects to return in this page. n/a

Response Codes

code condition
404 Returned when a cart is not found for the given cart ID.

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/{cartId}/items

Add a list of cart items to an existing cart. The item added to the cart can be internal or external to InService.

Example of an external item to be added to the cart 

{
"items": [
{
"attributes": {
"description": "",
"partNumber": "",
"quantity": ""
}
}]}

For internal items "e3cNavLink.itemId" attribute needs to be included in addition to quantity and description attribute. Internal items can also include a context that can be found as part of the NavLink information on the part.

Example of an internal item without context JSON structure 

{
"items": [
{
"attributes": {
"description": "",
"e3cNavLink.itemId": "",
"quantity": ""
}
}]}

Example of an internal item with context 

{
"items": [
{
"attributes": {
"description": "",
"e3cNavLink.contextId": "",
"e3cNavLink.itemId": "",
"e3cNavLink.itemParentId": "",
"quantity": ""
}
}]}

Request Parameters

name type description default
cartId path The ID of the cart to add the items to. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) The list of items to be added to the cart.

Response Codes

code condition
400 Returned when the content does not contain data or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

GET /carts/{cartId}/items/pricing

Retrieves the cart items total pricing of a specific cart.

Request Parameters

name type description default
cartId path The ID of the cart whose items pricing to retrieve. n/a
$expand query The OData expand parameter. $expand=totalCartPricing is used in the case when there is more objects in the cart then the one return. n/a
$top query The number of objects to return in this page. n/a

Response Codes

code condition
404 Returned when a cart is not found for the given cart ID.

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/{cartId}/items/update

Updates a list of cart items.

Request Parameters

name type description default
cartId path The ID of the cart that owns the items. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) The SCList of cart items to be updated.

Response Codes

code condition
400 Returned when the content does not contain data or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

PUT /carts/{cartId}/items/{itemId}

Updates a cart item.

Request Parameters

name type description default
cartId path The ID of the cart that owns the cart item. n/a
itemId path The ID of the cart item. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The cart item to be updated.

Response Codes

code condition
400 Returned when the content does not contain the correct cart item data for the update or the cartId or itemID are not of valid ID format.
404 Returned when a cart item is not found for the given cart ID and item ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCItem (JSON)

POST /carts/{cartId}/items/remove

Delete a list of existing cart items from the given cart.

Request Parameters

name type description default
cartId path The ID of the cart that owns the items. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCList (JSON) The SCList of cart items to be deleted.

Response Codes

code condition
204 Returned if a list of cart items were successfully deleted.
400 Returned when the content does not contain data or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

DELETE /carts/{cartId}/items/{itemId}

Deletes a cart item from the given cart.

Request Parameters

name type description default
cartId path The ID of the cart that owns the cart item. n/a
itemId path The ID of the cart item to be deleted. n/a
$expand query The OData expand parameter. $expand=pricing is used to inject pricing and availability n/a

Response Codes

code condition
204 Returned if the cart item was successfully deleted.
400 Returned when the cartId or itemId are not of valid ID format.
404 Returned when a cart item is not found for the given cart ID and item ID.

Response Body

media type data type
application/vnd.ptc.sc+json SCItem (JSON)

POST /carts/{cartId}/moveOrCopy

Copy/Move a list of existing cart/list items from the given cart/list.

Request Parameters

name type description default
cartId path The ID of the cart that owns the items. n/a

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The SCItem having attributes shouldCopy and targetId, and list of items to be copied/moved.

Response Codes

code condition
200 Returned if items were able to be moved/copied based on shouldCopy flag.
400 Returned when the content does not contain data or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)

POST /carts/moveOrCopyCarts

Copy/Move a list of existing cart/list items from the given cart/list.

Request Body

media type data type description
application/vnd.ptc.sc+json SCItem (JSON) The SCItem having attributes shouldCopy and targetId, and list of items to be copied/moved.

Response Codes

code condition
200 Returned if items were able to be moved/copied based on shouldCopy flag.
400 Returned when the content does not contain data or the cartId is not of valid ID format.
404 Returned when a cart is not found for the given cart ID.
415 Returned if the Content-Type is not application/vnd.ptc.sc+json;version=n

Response Body

media type data type
application/vnd.ptc.sc+json SCList (JSON)