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 the Composable Commerce support team and provide the Region, Project key and use case.

Representations

ShoppingList

ShoppingListDraft

ShoppingListPagedQueryResponse

ShoppingListReference

ShoppingListResourceIdentifier

Line Items -ShoppingListLineItem -ShoppingListLineItemDraft -TextLineItem -TextLineItemDraft

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	IDs and references that created the ShoppingList.
`lastModifiedAt` DateTime	Date and time (UTC) the ShoppingList was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the ShoppingList.

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"
}

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

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

ShoppingListReference

Reference to a ShoppingList.

`id` String	Unique identifier of the referenced ShoppingList.
`typeId` ReferenceTypeId	`"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. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique identifier of the referenced ShoppingList. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced ShoppingList. Required if `id` is absent.
`typeId` ReferenceTypeId	`"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.
`key` String	User-defined identifier of the ShoppingListLineItem. It is unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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"
}

ShoppingListLineItemDraft

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

`key` String	User-defined identifier of the ShoppingListLineItem. Must be unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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
}

TextLineItem

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

`id` String	Unique identifier of the TextLineItem.
`key` String	User-defined identifier of the TextLineItem. It is unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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"
}

TextLineItemDraft

`key` String	User-defined unique identifier of the TextLineItem. Must be unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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
}

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:

200ShoppingListasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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"
}

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:

200ShoppingListasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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"
}

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:

200ShoppingListasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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"
}

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:

200ShoppingListasapplication/json

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}'

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"
}

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. Default: `true`

Response:

200ShoppingListPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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

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. Default: `true`

Response:

200ShoppingListPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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

Check if ShoppingList exists

Check if ShoppingList exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}

Checks if a ShoppingList exists for a given id. Returns a 200 OK status if the ShoppingList exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShoppingList exists by Key

HEAD

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

Checks if a ShoppingList exists for a given key. Returns a 200 OK status if the ShoppingList exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShoppingList exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/shopping-lists

Checks if a ShoppingList exists for a given Query Predicate. Returns a 200 OK status if any ShoppingLists match the Query Predicate or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShoppingList exists in Store

Check if ShoppingList exists in Store by ID

HEAD

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

Checks if a ShoppingList exists for a given id. Returns a 200 OK status if the ShoppingList exists or a ResourceNotFound error otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShoppingList exists in Store by Key

HEAD

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

Checks if a ShoppingList exists for a given key. Returns a 200 OK status if the ShoppingList exists or a ResourceNotFound error otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShoppingList exists in Store by Query Predicate

HEAD

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

Checks if a ShoppingList exists for a given Query Predicate. Returns a 200 OK status if any ShoppingLists match the Query Predicate or a ResourceNotFound error otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shopping-lists -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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

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"
}

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

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"
}

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 ConcurrentModification error 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

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"
}

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 ConcurrentModification error 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

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"
}

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 ConcurrentModification error 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

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"
}

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 ConcurrentModification error 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

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"
}

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"
}

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"
  }
}

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"
  }
}

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"
  }
}

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}}"
  }
}

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"
  }
}

Set AnonymousId

If the Shopping List is already associated with a Customer, an InvalidOperation error is returned.

`action` String	`"setAnonymousId"`
`anonymousId` String	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setAnonymousId",
  "anonymousId": "anonymousId"
}

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"
  }
}

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"
}

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
}

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"`
`key` String	User-defined identifier of the ShoppingListLineItem. Must be unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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
}

Remove ShoppingListLineItem

`action` String	`"removeLineItem"`
`lineItemId` String	The `id` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`lineItemKey` String	The `key` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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
}

Change ShoppingListLineItem Quantity

`action` String	`"changeLineItemQuantity"`
`lineItemId` String	The `id` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`lineItemKey` String	The `key` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`quantity` Int	New value to set. If `0`, the ShoppingListLineItem is removed from the ShoppingList.

Example: json

{
  "action": "changeLineItemQuantity",
  "lineItemId": "{{lineItemId}}",
  "quantity": 8
}

Change ShoppingListLineItems Order

`action` String	`"changeLineItemsOrder"`
`lineItemOrder` Array of String	All existing ShoppingListLineItem `id`s in the desired new order.

Example: json

{
  "action": "changeLineItemsOrder",
  "lineItemOrder": ["{{lineItemId2}}", "{{lineItemId}}"]
}

Set ShoppingListLineItem Custom Type

`action` String	`"setLineItemCustomType"`
`lineItemId` String	The `id` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`lineItemKey` String	The `key` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
  }
}

Set ShoppingListLineItem CustomField

`action` String	`"setLineItemCustomField"`
`lineItemId` String	The `id` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`lineItemKey` String	The `key` of the ShoppingListLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
}

Update TextLineItems

Add TextLineItem

`action` String	`"addTextLineItem"`
`key` String	User-defined identifier of the TextLineItem. Must be unique per ShoppingList. MinLength: `2`MaxLength: `256`Pattern: `^[a-zA-Z0-9_-]`
`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"
  }
}

Remove TextLineItem

`action` String	`"removeTextLineItem"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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
}

Change TextLineItem Quantity

`action` String	`"changeTextLineItemQuantity"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`quantity` Int	New value to set. If `0`, the TextLineItem is removed from the ShoppingList.

Example: json

{
  "action": "changeTextLineItemQuantity",
  "textLineItemId": "{{lineItemId}}",
  "quantity": 1
}

Change TextLineItem Name

`action` String	`"changeTextLineItemName"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
  }
}

Set TextLineItem Description

`action` String	`"setTextLineItemDescription"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
  }
}

Change TextLineItems Order

`action` String	`"changeTextLineItemsOrder"`
`textLineItemOrder` Array of String	Must contain all existing TextLineItem `id`s in the desired new order.

Example: json

{
  "action": "changeTextLineItemsOrder",
  "textLineItemOrder": ["{{lineItemId2}}", "{{lineItemId}}"]
}

Set TextLineItem Custom Type

`action` String	`"setTextLineItemCustomType"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
  }
}

Set TextLineItem CustomField

`action` String	`"setTextLineItemCustomField"`
`textLineItemId` String	The `id` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`textLineItemKey` String	The `key` of the TextLineItem to update. Either `lineItemId` or `lineItemKey` is required.
`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"
}

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	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200ShoppingListasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shopping-lists/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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"
}

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	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200ShoppingListasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shopping-lists/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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"
}

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	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200ShoppingListasapplication/json

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}'

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"
}

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	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200ShoppingListasapplication/json

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}'

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"
}

Shopping Lists

Representations

ShoppingList

ShoppingListDraft

ShoppingListPagedQueryResponse

ShoppingListReference

ShoppingListResourceIdentifier

Line Items

ShoppingListLineItem

ShoppingListLineItemDraft

TextLineItem

TextLineItemDraft

Get ShoppingList

Get ShoppingList by ID

Get ShoppingList by Key

Get ShoppingList in Store

Get ShoppingList in Store by ID

Get ShoppingList in Store by Key

Query ShoppingLists

Query ShoppingLists in Store

Check if ShoppingList exists

Check if ShoppingList exists by ID

Check if ShoppingList exists by Key

Check if ShoppingList exists by Query Predicate

Check if ShoppingList exists in Store

Check if ShoppingList exists in Store by ID

Check if ShoppingList exists in Store by Key

Check if ShoppingList exists in Store by Query Predicate

Create ShoppingList

Create ShoppingList in Store

Update ShoppingList

Update ShoppingList by ID

Update ShoppingList by Key

Update ShoppingList in Store

Update ShoppingList in Store by ID

Update ShoppingList in Store by Key

Update actions

Set Key

Set Slug

Change Name

Set Description

Set Customer

Set Store

Set AnonymousId

Set Custom Type

Set CustomField

Set DeleteDaysAfterLastModification

Update ShoppingListLineItems

Add ShoppingListLineItem

Remove ShoppingListLineItem

Change ShoppingListLineItem Quantity

Change ShoppingListLineItems Order

Set ShoppingListLineItem Custom Type

Set ShoppingListLineItem CustomField

Update TextLineItems

Add TextLineItem

Remove TextLineItem

Change TextLineItem Quantity

Change TextLineItem Name

Set TextLineItem Description

Change TextLineItems Order

Set TextLineItem Custom Type

Set TextLineItem CustomField

Delete ShoppingList

Delete ShoppingList by ID

Delete ShoppingList by Key

Delete ShoppingList in Store

Delete ShoppingList in Store by ID

Delete ShoppingList in Store by Key