Work with the purchase list API
The purchase list API allows you to create purchase lists that are accessible only on specific sites, or for account-based shoppers, only on specific sites and/or accounts.
The API also allows you to create purchase lists that are accessible in all contexts, like the purchase lists that are created using the UI, as well as to create custom properties for line items.
The following tasks can be performed using the purchase list API. For additional information on working with APIs, refer to the Use the REST APIs.
Create a purchase list with the API
When a shopper creates a purchase list, it is available in all site and account contexts for consumer commerce or account based-commerce, however, you can specify specific sites and/or accounts.
Issue a POST
request to /ccstore/v1/purchaseLists
. For example:
{
"name":"Purchase List 1",
"description":"Purchase List",
"siteId":"siteUS",
"accountId":"or-100001",
"items": [{
"productId":"Product_18Cxi",
"catRefId": "Sku_18Dxi",
"quantityDesired" : 25
},
{
"productId":"Product_5Cx",
"catRefId": "Sku_5Cxy",
"quantityDesired" : 30
}
]
}
Update a purchase list with the API
To update a purchase list issue a PUT
request in the following format: /ccstore/v1/purchaseLists/{id}
where you provide the purchase list ID. For example, you could use the following to update the name or description of the purchase list with the following:
PUT /ccstore/v1/purchaseLists/gl42244
To update a specific purchase list item, use the /ccstore/v1/purchaseLists/{id}/updateItems
. The following example removes one of the products:
{
"items": [{
"productId":"Product_18Cxi",
"catRefId": "Sku_18Dxi",
"quantityDesired" : 25,
"op": "update"
},
{
"productId":"Product_5Cx",
"catRefId": "Sku_5Cxy",
"quantityDesired" : 100,
"op": "delete"
}
]
}
Delete a purchase list with the API
To remove a purchase list, issue a DELETE
request and the ID of the purchase list. For example:
DELETE /ccstore/v1/purchaseLists/gl42244
Once the purchase list has been removed, the shopper will get a confirmation prompt.
Use custom properties on purchase lists and their line items
You can use the API to add custom properties to a purchase list itself, or a purchase list's line items.
updateItemType
endpoint to create new custom properties. You can also use this API to update existing custom properties. Purchase lists are accessed from the gift-list
item type. To create or update a custom property for the gift-list
, issue a PUT
command in the request body as follows://updateItemType
PUT /ccadmin/v1/itemTypes/gift-list
{
"specifications": [
{
"id": "customPLProperty_1",
"label": "Custom PL Property 1",
"type": "shortText",
"uiEditorType": "shortText",
"required": false,
"default": null,
"searchable": true,
"localizable": false
}
]
}
DELETE
command://deleteitemTypeProperty
DELETE /ccadmin/v1/itemTypes/gift-list/properties/customPLProperty_1
getItemType
API://getItemType
GET /ccadmin/v1/itemTypes/gift-list
GET /ccagent/v1/itemTypes/gift-list
GET /ccstore/v1/itemTypes/gift-list
Create custom properties for line items
You can create custom properties for purchase list line items, which allows you to do such things as add notes to a purchase list item or provide additional product information about the item. Custom properties can be used by the purchase list widget, as described in Configure Purchase Lists. You can expose the property in your customized purchase list widget. You can customize the widget code using copies of an item from a purchase list to a cart such that when it copies the item, it also copies the content of the custom property to a custom property that has already been defined on the order line item.
gift-item
item type. To create or update a custom property for the gift-item
item type, issue a PUT
command in the request body as follows://updateItemType
PUT /ccadmin/v1/itemTypes/gift-item
{
"specifications": [
{
"id": "customPLIProperty_1",
"label": "Custom PL Item Property 1",
"type": "shortText",
"uiEditorType": "shortText",
"required": false,
"default": null,
"searchable": true,
"localizable": false
}
]
}
DELETE
command:DELETE /ccadmin/v1/itemTypes/gift-item/properties/customPLIProperty_1
getItemType
API:GET /ccadmin/v1/itemTypes/gift-item
GET /ccagent/v1/itemTypes/gift-item
GET /ccstore/v1/itemTypes/gift-item
updateItems
API to modify custom properties on purchase list line items. For example://updateItems
POST /ccstore/v1/purchaseLists/gl10001/updateItems
POST /ccagent/v1/purchaseLists/gl10001/updateItems
{
"items": [
{
"op": "add",
"productId": "Product_18Cxi",
"quantityDesired": 25,
"catRefId": "Sku_18Dxi",
"customPLIProperty_1": "Value for customPLIProperty_1 property for PurchaseList1's item Product_18Cxi"
},
{
"op": "update",
"productId": "Product_5Cx",
"quantityDesired": 30,
"catRefId": "Sku_5Cxy",
"customPLIProperty_1": "Value for customPLIProperty_1 property for PurchaseList1's item Product_5Cx"
}
]
}
//createPurchaseList
POST /ccstore/v1/purchaseLists
POST /ccagent/v1/purchaseLists
// updatePurchaseList
PUT /ccstore/v1/purchaseLists/gl10001
PUT /ccagent/v1/purchaseLists/gl10001
{
"customPLStringProperty_1": "Value for customPLProperty_1 property for PurchaseList1",
"accountId": "or-100001",
"name": "PurchaseList1",
"description": "PurchaseList",
"siteId": "siteUS",
"items": [
{
"productId": "Product_18Cxi",
"quantityDesired": 25,
"catRefId": "Sku_18Dxi",
"customPLIProperty_1": "Value for customPLIProperty_1 property for PurchaseList1's item Product_18Cxi"
},
{
"productId": "Product_5Cx",
"quantityDesired": 30,
"catRefId": "Sku_5Cxy",
"customPLIProperty_1": "Value for customPLIProperty_1 property for PurchaseList1's item Product_5Cx"
}
]
}
Anyone who has edit access to a purchase list can update the value of a custom property on a purchase list line item, although only the owner of a purchase list can update the value of a custom property that resides on the purchase list itself.