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.

Use the 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
    }
  ]
}

To delete a custom property for a purchase list, issue a DELETE command:

//deleteitemTypeProperty
DELETE /ccadmin/v1/itemTypes/gift-list/properties/customPLProperty_1 

You can review the metadata of the custom property by using the 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.

Items in a purchase list are accessed from the 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
    }
  ]
}

To delete a custom line item property, issue a DELETE command:

DELETE /ccadmin/v1/itemTypes/gift-item/properties/customPLIProperty_1

You can review the metadata of the custom property by using the getItemType API:

GET /ccadmin/v1/itemTypes/gift-item
GET /ccagent/v1/itemTypes/gift-item
GET /ccstore/v1/itemTypes/gift-item

Use the 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"
    }
  ]
}

When you update or create a custom purchase list line item, the custom properties that you create can be included as part of the request payloads from either the storefront or the agent APIs. You can also pass values for custom properties on the purchase list line items in the request payload when you are creating or updating a purchase list. For example:

//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.