Documentation

Shopping Lists

A Shopping List can be used to implement a "save-for-later" feature for an individual Customer, a shareable wishlist, or a public collection of Products.

Shopping Lists typically have Line Items: ShoppingListLineItems that contain Products and/or TextLineItems that use text values to represent any other item.

A Shopping List can contain up to 250 Line Items and up to 100 Text Line Items. The maximum number of Shopping Lists that can be added to a Project is 10 000 000. If your Project contains more Shopping Lists, the oldest unmodified resources are automatically deleted.

These limits can be increased per Project after we review the performance impact. Please contact Support via the Support PortalExternal link icon and provide the Region, Project key and use case.

Representations

ShoppingList

id​
String​

Unique identifier of the ShoppingList.

version​
Int​

Current version of the ShoppingList.

key​
String​

User-defined unique identifier of the ShoppingList.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
LocalizedString​

Name of the ShoppingList.

customer​
CustomerReference​

Reference to a Customer associated with the ShoppingList.

slug​
LocalizedString​

Human-readable identifiers usually used as deep-link URL to the related ShoppingList. Each slug is unique across a Project, but a ShoppingList can have the same slug for different languages. The slug must match the pattern [a-zA-Z0-9_-]{2,256}. For good performance, indexes are provided for the first 15 languages set on the Project.

description​
LocalizedString​

Description of the ShoppingList.

lineItems​
Array of ShoppingListLineItem​

Line Items (containing Products) of the ShoppingList.

textLineItems​
Array of TextLineItem​

Line Items (containing text values) of the ShoppingList.

deleteDaysAfterLastModification​
Int​

Number of days after which the ShoppingList will be automatically deleted if it has not been modified.

anonymousId​
String​

Identifies ShoppingLists belonging to an anonymous session.

store​
StoreKeyReference​

Store to which the ShoppingList is assigned.

custom​
CustomFields​

Custom Fields defined for the ShoppingList.

createdAt​
DateTime​

Date and time (UTC) the ShoppingList was initially created.

createdBy​BETA
CreatedBy​

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt​
DateTime​

Date and time (UTC) the ShoppingList was last updated.

lastModifiedBy​BETA
LastModifiedBy​

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

ShoppingListDraft

key​
String​

User-defined unique identifier for the ShoppingList.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
LocalizedString​

Name of the ShoppingList.

slug​
LocalizedString​

Human-readable identifiers usually used as deep-link URL to the related ShoppingList. Each slug is unique across a Project, but a ShoppingList can have the same slug for different languages. The slug must match the pattern [a-zA-Z0-9_-]{2,256}.

customer​
CustomerResourceIdentifier​

The Customer the ShoppingList should be associated to.

description​
LocalizedString​

Description of the ShoppingList.

anonymousId​
String​

Identifies ShoppingLists belonging to an anonymous session.

deleteDaysAfterLastModification​
Int​

Number of days after which the ShoppingList will be automatically deleted if it has not been modified. If not set, the default value configured in the Project is used.

Minimum: 1​
lineItems​
Array of ShoppingListLineItemDraft​

Line Items (containing Products) to add to the ShoppingList.

textLineItems​
Array of TextLineItemDraft​

Line Items (containing text values) to add to the ShoppingList.

store​
StoreResourceIdentifier​

Assigns the new ShoppingList to the Store.

custom​
CustomFieldsDraft​

Custom Fields defined for the ShoppingList.

Example: json
{
  "name" : {
    "en" : "My shopping list"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "key" : "my-shopping-list",
  "deleteDaysAfterLastModification" : 100,
  "lineItems" : [ {
    "sku" : "product-variant-sku",
    "quantity" : 5
  }, {
    "productId" : "0e131f46-8d1a-4761-9c83-b45ab5d3501e",
    "variantId" : 2
  } ],
  "textLineItems" : [ {
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5
  } ]
}
Clipboard icon

ShoppingListPagedQueryResponse

limit​
Int​

Number of results requested.

count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

offset​
Int​

Number of elements skipped.

results​
Array of ShoppingList​

ShoppingLists matching the query.

Example: json
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "9693f04b-5aec-467f-baa1-fc74da7d0c3d",
    "version" : 1,
    "name" : {
      "en" : "test"
    },
    "key" : "test",
    "lineItems" : [ ],
    "textLineItems" : [ ],
    "createdAt" : "2017-03-30T11:49:40.904Z",
    "lastModifiedAt" : "2017-03-30T11:49:40.904Z"
  } ]
}
Clipboard icon

ShoppingListReference

Reference to a ShoppingList.

id​
String​

Unique identifier of the referenced ShoppingList.

typeId​
String​
"shopping-list"

References a ShoppingList.

obj​
ShoppingList​

Contains the representation of the expanded ShoppingList. Only present in responses to requests with Reference Expansion for ShoppingLists.

ShoppingListResourceIdentifier

ResourceIdentifier to a ShoppingList.

id​
String​

Unique identifier of the referenced ShoppingList. Either id or key is required.

key​
String​

User-defined unique identifier of the referenced ShoppingList. Either id or key is required.

typeId​
String​
"shopping-list"

References a ShoppingList.

Line Items

ShoppingListLineItem

ShoppingListLineItems are Line Items that contain references to ProductVariants in a Product.

In addition to standard Reference Expansion, a ShoppingListLineItem offers expansion on productSlug and variant, defined with the query parameter expand.

id​
String​

Unique identifier of the ShoppingListLineItem.

addedAt​
DateTime​

Date and time (UTC) the ShoppingListLineItem was added to the ShoppingList.

deactivatedAt​
DateTime​

If the Product or Product Variant is deleted, deactivatedAt is the date and time (UTC) of deletion.

This data is updated in an eventual consistent manner when the Product Variant cannot be ordered anymore.

name​
LocalizedString​

Name of the Product.

This data is updated in an eventual consistent manner when the Product's name changes.

productId​
String​

Unique identifier of a Product.

productType​
ProductTypeReference​

The Product Type defining the Attributes of the Product.

quantity​
Int​

Number of Products in the ShoppingListLineItem.

variantId​
Int​

id of the ProductVariant the ShoppingListLineItem refers to. If not set, the ShoppingListLineItem refers to the Master Variant.

variant​
ProductVariant​

Data of the ProductVariant.

Returned when expanded using expand=lineItems[*].variant. You cannot expand only a single element of the array.

productSlug​
LocalizedString​

Slug of the current ProductData.

Returned when expanded using expand=lineItems[*].productSlug. You cannot expand only a single element of the array.

custom​
CustomFields​

Custom Fields of the ShoppingListLineItem.

Example: json
{
  "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
  "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
  "name" : {
    "en" : "Product name"
  },
  "productType" : {
    "typeId" : "product-type",
    "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
  },
  "variantId" : 2,
  "quantity" : 3,
  "addedAt" : "2022-08-22T14:11:03.572Z"
}
Clipboard icon

ShoppingListLineItemDraft

The ProductVariant to be included in the ShoppingListLineItem must be specified using the productID and variantID, or by the sku.

productId​
String​

Unique identifier of a Product.

variantId​
Int​

id of the ProductVariant. If not set, the ShoppingListLineItem refers to the Master Variant.

sku​
String​

sku of the ProductVariant.

addedAt​
DateTime​

Date and time the ShoppingListLineItem is added to the ShoppingList. If not set, the current date and time (UTC) is used.

quantity​
Int​

Number of Products in the ShoppingListLineItem.

Default: 1​Minimum: 1​
custom​
CustomFieldsDraft​

Custom Fields of the ShoppingListLineItem.

Example: json
{
  "sku" : "product-variant-sku",
  "quantity" : 3
}
Clipboard icon

TextLineItem

TextLineItems are Line Items that use text values instead of references to Products.

id​
String​

Unique identifier of the TextLineItem.

addedAt​
DateTime​

Date and time (UTC) the TextLineItem was added to the ShoppingList.

description​
LocalizedString​

Description of the TextLineItem.

name​
LocalizedString​

Name of the TextLineItem.

quantity​
Int​

Number of entries in the TextLineItem.

custom​
CustomFields​

Custom Fields of the TextLineItem.

Example: json
{
  "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
  "name" : {
    "en" : "My shopping list item"
  },
  "description" : {
    "en" : "This is a good gift idea"
  },
  "quantity" : 5,
  "addedAt" : "2022-08-22T14:11:03.572Z"
}
Clipboard icon

TextLineItemDraft

addedAt​
DateTime​

Date and time the TextLineItem is added to the ShoppingList. If not set, the current date and time (UTC) is used.

description​
LocalizedString​

Description of the TextLineItem.

name​
LocalizedString​

Name of the TextLineItem.

quantity​
Int​

Number of entries in the TextLineItem.

Default: 1​Minimum: 1​
custom​
CustomFieldsDraft​

Custom Fields for the TextLineItem.

Example: json
{
  "name" : {
    "en" : "My shopping list item"
  },
  "description" : {
    "en" : "This is a good gift idea"
  },
  "quantity" : 5
}
Clipboard icon

Get ShoppingList

Get ShoppingList by ID

GET
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}
OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Response:
200ShoppingList
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Get ShoppingList by Key

GET
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key}
OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Response:
200ShoppingList
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Get ShoppingList in Store

Get ShoppingList in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Response:
200ShoppingList
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Get ShoppingList in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Response:
200ShoppingList
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Query ShoppingLists

GET
https://api.{region}.commercetools.com/{projectKey}/shopping-lists
OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​
Any string parameter matching this regular expression
​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200ShoppingListPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "9693f04b-5aec-467f-baa1-fc74da7d0c3d",
    "version" : 1,
    "name" : {
      "en" : "test"
    },
    "key" : "test",
    "lineItems" : [ ],
    "textLineItems" : [ ],
    "createdAt" : "2017-03-30T11:49:40.904Z",
    "lastModifiedAt" : "2017-03-30T11:49:40.904Z"
  } ]
}
Clipboard icon

Query ShoppingLists in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists
OAuth 2.0 Scopes:
view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​
Any string parameter matching this regular expression
​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​

Limitation: expand=lineItems[0].variant and expand=lineItems[0].productSlug are not supported.

The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200ShoppingListPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "9693f04b-5aec-467f-baa1-fc74da7d0c3d",
    "version" : 1,
    "name" : {
      "en" : "test"
    },
    "key" : "test",
    "lineItems" : [ ],
    "textLineItems" : [ ],
    "createdAt" : "2017-03-30T11:49:40.904Z",
    "lastModifiedAt" : "2017-03-30T11:49:40.904Z"
  } ]
}
Clipboard icon

Create ShoppingList

POST
https://api.{region}.commercetools.com/{projectKey}/shopping-lists
OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Request Body:ShoppingListDraftasapplication/json
Response:
201ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : {
    "en" : "My shopping list"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "key" : "my-shopping-list",
  "deleteDaysAfterLastModification" : 100,
  "lineItems" : [ {
    "sku" : "product-variant-sku",
    "quantity" : 5
  }, {
    "productId" : "0e131f46-8d1a-4761-9c83-b45ab5d3501e",
    "variantId" : 2
  } ],
  "textLineItems" : [ {
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5
  } ]
}
DATA
Clipboard icon
201 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Create ShoppingList in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists

When using this endpoint, the store field of a ShoppingList is always set to the Store specified in the path parameter.

OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
expand
​
Expansion
​

Limitation: expand=lineItems[0].variant and expand=lineItems[0].productSlug are not supported.

The parameter can be passed multiple times.
Request Body:ShoppingListDraftasapplication/json
Response:
201ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : {
    "en" : "My shopping list"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "key" : "my-shopping-list",
  "deleteDaysAfterLastModification" : 100,
  "lineItems" : [ {
    "sku" : "product-variant-sku",
    "quantity" : 5
  }, {
    "productId" : "0e131f46-8d1a-4761-9c83-b45ab5d3501e",
    "variantId" : 2
  } ],
  "textLineItems" : [ {
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5
  } ]
}
DATA
Clipboard icon
201 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Update ShoppingList

Update ShoppingList by ID

POST
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}
OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShoppingList on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShoppingListUpdateAction​

List of update actions to be performed on the ShoppingList.

Response:
200ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "New Name"
    }
  } ]
}
DATA
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Update ShoppingList by Key

POST
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key}
OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShoppingList on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShoppingListUpdateAction​

List of update actions to be performed on the ShoppingList.

Response:
200ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "New Name"
    }
  } ]
}
DATA
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Update ShoppingList in Store

Update ShoppingList in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShoppingList on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShoppingListUpdateAction​

List of update actions to be performed on the ShoppingList.

Response:
200ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "New Name"
    }
  } ]
}
DATA
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Update ShoppingList in Store by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the ShoppingList.

Query parameters:
expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShoppingList on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShoppingListUpdateAction​

List of update actions to be performed on the ShoppingList.

Response:
200ShoppingListasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : {
      "en" : "New Name"
    }
  } ]
}
DATA
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Update actions

Set Key

action​
String​
"setKey"
key​
String​

Value to set. If empty, any existing value will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action" : "setKey",
  "key" : "new-shopping-list-key"
}
Clipboard icon

Set Slug

action​
String​
"setSlug"
slug​
LocalizedString​

Value to set. If empty, any existing value will be removed. Each slug is unique across a Project, but a ShoppingList can have the same slug for different languages. Must match the pattern ^[A-Za-z0-9_-]{2,256}+$

Example: json
{
  "action" : "setSlug",
  "slug" : {
    "en" : "en-slug",
    "de" : "de-slug"
  }
}
Clipboard icon

Change Name

action​
String​
"changeName"
name​
LocalizedString​

New value to set. Must not be empty.

Example: json
{
  "action" : "changeName",
  "name" : {
    "de" : "German name",
    "en" : "English name"
  }
}
Clipboard icon

Set Description

action​
String​
"setDescription"
description​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setDescription",
  "description" : {
    "en" : "New description",
    "de" : "Neue Beschreibung"
  }
}
Clipboard icon

Set Customer

action​
String​
"setCustomer"
customer​
CustomerResourceIdentifier​

The Customer the ShoppingList should be associated to. If empty, any existing value will be removed.

Example: json
{
  "action" : "setCustomer",
  "customer" : {
    "typeId" : "customer",
    "id" : "{{customer-id}}"
  }
}
Clipboard icon

Set Store

action​
String​
"setStore"
store​
StoreResourceIdentifier​

The Store the ShoppingList should be assigned to. If empty, any existing value will be removed.

Example: json
{
  "action" : "setStore",
  "store" : {
    "key" : "{{store-key}}",
    "typeId" : "store"
  }
}
Clipboard icon

Set AnonymousId

action​
String​
"setAnonymousId"
anonymousId​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setAnonymousId",
  "anonymousId" : "ThisIsMyID"
}
Clipboard icon

Set Custom Type

action​
String​
"setCustomType"
type​
TypeResourceIdentifier​

Defines the Type that extends the ShoppingList with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShoppingList.

fields​
FieldContainer​

Sets the Custom Fields fields for the ShoppingList.

Example: json
{
  "action" : "setCustomType",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "exampleStringTypeField" : "TextString"
  }
}
Clipboard icon

Set CustomField

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action" : "setCustomField",
  "name" : "ExampleStringTypeField",
  "value" : "TextString"
}
Clipboard icon

Set DeleteDaysAfterLastModification

action​
String​
"setDeleteDaysAfterLastModification"
deleteDaysAfterLastModification​
Int​

Value to set. If empty, any existing value will be removed.

Minimum: 1​
Example: json
{
  "action" : "setDeleteDaysAfterLastModification",
  "deleteDaysAfterLastModification" : 10
}
Clipboard icon

Update ShoppingListLineItems

Add ShoppingListLineItem

The ProductVariant to be included in the ShoppingListLineItem must be specified using the productID and variantID, or by the sku. If the ShoppingList already contains a ShoppingListLineItem for the same Product Variant with the same Custom Fields, then only the quantity of the existing ShoppingListLineItem is increased. A ShoppingListLineItem with an empty variantId is not considered the same as a ShoppingListLineItem with a variantId currently referring to the Master Variant.

action​
String​
"addLineItem"
sku​
String​

sku of the ProductVariant.

productId​
String​

Unique identifier of a Product.

variantId​
Int​

id of the ProductVariant. If not set, the ShoppingListLineItem refers to the Master Variant.

quantity​
Int​

Number of Products in the ShoppingListLineItem.

Default: 1​Minimum: 1​
addedAt​
DateTime​

Date and time the TextLineItem is added to the ShoppingList. If not set, the current date and time (UTC) is used.

custom​
CustomFieldsDraft​

Custom Fields defined for the ShoppingListLineItem.

Example: json
{
  "action" : "addLineItem",
  "productId" : "{{product-id}}",
  "variantId" : 1,
  "quantity" : 2
}
Clipboard icon

Remove ShoppingListLineItem

action​
String​
"removeLineItem"
lineItemId​
String​

The id of the ShoppingListLineItem to update.

quantity​
Int​

Amount to remove from the quantity of the ShoppingListLineItem. If not set, the ShoppingListLineItem is removed from the ShoppingList. If this value matches or exceeds the current quantity of the ShoppingListLineItem, the ShoppingListLineItem is removed from the ShoppingList.

Minimum: 1​
Example: json
{
  "action" : "removeLineItem",
  "lineItemId" : "{{lineItemId}}",
  "quantity" : 2
}
Clipboard icon

Change ShoppingListLineItem Quantity

action​
String​
"changeLineItemQuantity"
lineItemId​
String​

The id of the ShoppingListLineItem to update.

quantity​
Int​

New value to set. If 0, the ShoppingListLineItem is removed from the ShoppingList.

Example: json
{
  "action" : "changeLineItemQuantity",
  "lineItemId" : "{{lineItemId}}",
  "quantity" : 8
}
Clipboard icon

Change ShoppingListLineItems Order

action​
String​
"changeLineItemsOrder"
lineItemOrder​
Array of String​

All existing ShoppingListLineItem ids in the desired new order.

Example: json
{
  "action" : "changeLineItemsOrder",
  "lineItemOrder" : [ "{{lineItemId2}}", "{{lineItemId}}" ]
}
Clipboard icon

Set ShoppingListLineItem Custom Type

action​
String​
"setLineItemCustomType"
lineItemId​
String​

The id of the ShoppingListLineItem to update.

type​
TypeResourceIdentifier​

Defines the Type that extends the ShoppingListLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShoppingListLineItem.

fields​
FieldContainer​

Sets the Custom Fields fields for the ShoppingListLineItem.

Example: json
{
  "action" : "setLineItemCustomType",
  "lineItemId" : "{{lineItemId}}",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "exampleStringTypeField" : "TextString"
  }
}
Clipboard icon

Set ShoppingListLineItem CustomField

action​
String​
"setLineItemCustomField"
lineItemId​
String​

The id of the ShoppingListLineItem to update.

name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action" : "setLineItemCustomField",
  "lineItemId" : "{{lineItemId}}",
  "name" : "ExampleStringTypeField",
  "value" : "TextString"
}
Clipboard icon

Update TextLineItems

Add TextLineItem

action​
String​
"addTextLineItem"
name​
LocalizedString​

Name of the TextLineItem.

description​
LocalizedString​

Description of the TextLineItem.

quantity​
Int​

Number of entries in the TextLineItem.

Default: 1​
addedAt​
DateTime​

Date and time the TextLineItem is added to the ShoppingList. If not set, the current date and time (UTC) is used.

custom​
CustomFieldsDraft​

Custom Fields defined for the TextLineItem.

Example: json
{
  "action" : "addTextLineItem",
  "name" : {
    "de" : "German name for text line item",
    "en" : "English name for text line item"
  }
}
Clipboard icon

Remove TextLineItem

action​
String​
"removeTextLineItem"
textLineItemId​
String​

The id of the TextLineItem to update.

quantity​
Int​

Amount to remove from the quantity of the TextLineItem. If not set, the TextLineItem is removed from the ShoppingList. If this value matches or exceeds the current quantity of the TextLineItem, the TextLineItem is removed from the ShoppingList.

Minimum: 1​
Example: json
{
  "action" : "removeTextLineItem",
  "textLineItemId" : "{{lineItemId}}",
  "quantity" : 1
}
Clipboard icon

Change TextLineItem Quantity

action​
String​
"changeTextLineItemQuantity"
textLineItemId​
String​

The id of the TextLineItem to update.

quantity​
Int​

New value to set. If 0, the TextLineItem is removed from the ShoppingList.

Example: json
{
  "action" : "changeTextLineItemQuantity",
  "textLineItemId" : "{{lineItemId}}",
  "quantity" : 1
}
Clipboard icon

Change TextLineItem Name

action​
String​
"changeTextLineItemName"
textLineItemId​
String​

The id of the TextLineItem to update.

name​
LocalizedString​

New value to set. Must not be empty.

Example: json
{
  "action" : "changeTextLineItemName",
  "textLineItemId" : "{{lineItemId}}",
  "name" : {
    "de" : "New German text line item name",
    "en" : "New English text line item name"
  }
}
Clipboard icon

Set TextLineItem Description

action​
String​
"setTextLineItemDescription"
textLineItemId​
String​

The id of the TextLineItem to update.

description​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setTextLineItemDescription",
  "textLineItemId" : "{{lineItemId}}",
  "description" : {
    "en" : "New description",
    "de" : "Neue Beschreibung"
  }
}
Clipboard icon

Change TextLineItems Order

action​
String​
"changeTextLineItemsOrder"
textLineItemOrder​
Array of String​

Must contain all existing TextLineItem ids in the desired new order.

Example: json
{
  "action" : "changeTextLineItemsOrder",
  "textLineItemOrder" : [ "{{lineItemId2}}", "{{lineItemId}}" ]
}
Clipboard icon

Set TextLineItem Custom Type

action​
String​
"setTextLineItemCustomType"
textLineItemId​
String​

The id of the TextLineItem to update.

type​
TypeResourceIdentifier​

Defines the Type that extends the TextLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the TextLineItem.

fields​
FieldContainer​

Sets the Custom Fields fields for the TextLineItem.

Example: json
{
  "action" : "setTextLineItemCustomType",
  "textLineItemId" : "{{lineItemId}}",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "exampleStringTypeField" : "TextString"
  }
}
Clipboard icon

Set TextLineItem CustomField

action​
String​
"setTextLineItemCustomField"
textLineItemId​
String​

The id of the TextLineItem to update.

name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action" : "setTextLineItemCustomField",
  "textLineItemId" : "{{lineItemId}}",
  "name" : "ExampleStringTypeField",
  "value" : "TextString"
}
Clipboard icon

Delete ShoppingList

Delete ShoppingList by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}
OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShoppingList.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
dataErasure
​
Boolean
​

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200ShoppingList
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Delete ShoppingList by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key}
OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShoppingList.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
dataErasure
​
Boolean
​

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200ShoppingList
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Delete ShoppingList in Store

Delete ShoppingList in Store by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the ShoppingList.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
dataErasure
​
Boolean
​

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200ShoppingList
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon

Delete ShoppingList in Store by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}

If a ShoppingList exists in a Project but does not have the store field, or the store field references a different Store, the ResourceNotFound error is returned.

OAuth 2.0 Scopes:
manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the ShoppingList.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​

When expanding variant and productSlug on ShoppingListLineItem, expand the entire array. You cannot expand a single element (for example, expand=lineItems[0].variant is not supported).

The parameter can be passed multiple times.
dataErasure
​
Boolean
​

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
200ShoppingList
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShoppingListjson
{
  "id" : "acb58513-ccfd-4ee8-8f28-9b7238fb91cd",
  "version" : 1,
  "name" : {
    "en" : "My shopping list"
  },
  "key" : "my-shopping-list",
  "customer" : {
    "typeId" : "customer",
    "id" : "e73cd97f-846e-44a0-b418-3ed044a8e398"
  },
  "slug" : {
    "en" : "my-shopping-list"
  },
  "lineItems" : [ {
    "id" : "ade85d60-736b-4ca8-87ed-01fde78f92c5",
    "productId" : "077bb11b-0d00-4e00-aced-48f493a79da0",
    "name" : {
      "en" : "Product name"
    },
    "productType" : {
      "typeId" : "product-type",
      "id" : "a941b0b1-5c8f-41de-99e4-de965714d89f"
    },
    "variantId" : 2,
    "quantity" : 1,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "textLineItems" : [ {
    "id" : "c25aaca9-bb25-4a9f-bb1f-be0a78e98dcb",
    "name" : {
      "en" : "My shopping list item"
    },
    "description" : {
      "en" : "This is a good gift idea"
    },
    "quantity" : 5,
    "addedAt" : "2022-08-22T14:11:03.572Z"
  } ],
  "deleteDaysAfterLastModification" : 100,
  "createdAt" : "2022-08-22T14:11:03.587Z",
  "lastModifiedAt" : "2022-08-22T14:11:03.587Z"
}
Clipboard icon