[go: up one dir, main page]

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. Contact the Composable Commerce support team and provide the Region, Project key and use case.
Learn more about how to utilize Shopping Lists in our self-paced Implement Shopping Lists module.

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.

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
name

Name of the ShoppingList.

customer
Reference to a Customer associated with the ShoppingList.
slug
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

Description of the ShoppingList.

lineItems

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 the last modification before a ShoppingList is deleted. If not set, the default value configured in the Project is used.
Default360Minimum1Maximum365250
anonymousId
String
Identifies ShoppingLists belonging to an anonymous session.
store

Store to which the ShoppingList is assigned.

businessUnit
Reference to the Business Unit the Shopping List belongs to. Only available for B2B-enabled Projects.
custom

Custom Fields defined for the ShoppingList.

createdAt

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

createdByBETA

IDs and references that created the ShoppingList.

lastModifiedAt

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

lastModifiedByBETA

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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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.

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
name

Name of the ShoppingList.

slug
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
The Customer the ShoppingList should be associated to.
description

Description of the ShoppingList.

anonymousId
String
Identifies ShoppingLists belonging to an anonymous session.
deleteDaysAfterLastModification
Int
Number of days after the last modification before a ShoppingList is deleted. If not set, the default value configured in the Project is used.
Minimum1Maximum365250
lineItems

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

textLineItems
Array of TextLineItemDraft

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

store
Assigns the new ShoppingList to the Store.
businessUnit
ResourceIdentifier of the Business Unit the Shopping List should belong to. When the customer of the Shopping List is set, the Customer must be an Associate of the Business Unit. Only available for B2B-enabled Projects.
custom

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
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  }
}

ShoppingListPagedQueryResponse

limit
Int
Default20Minimum0Maximum500
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.
Default0Maximum10000
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": [],
      "businessUnit": {
        "key": "bu-345-france",
        "typeId": "business-unit"
      },
      "createdAt": "2017-03-30T11:49:40.904Z",
      "lastModifiedAt": "2017-03-30T11:49:40.904Z"
    }
  ]
}

ShoppingListReference

id
String
Unique identifier of the referenced ShoppingList.
typeId
shopping-list

Type of referenced resource.

obj
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
shopping-list
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

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.
MinLength2MaxLength256Pattern^[a-zA-Z0-9_-]
addedAt

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

deactivatedAt
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

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
The Product Type defining the Attributes of the Product.
published
Boolean
Whether the related Product is published or not.
This data is updated in an eventual consistent manner when the Product's published status changes.
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
Data of the ProductVariant. This data includes all the Product Attributes and Variant Attributes to ensure the full Attribute context of the Product Variant.
Returned when expanded using expand=lineItems[*].variant. You cannot expand only a single element of the array.
productSlug
Slug of the current ProductData.
Returned when expanded using expand=lineItems[*].productSlug. You cannot expand only a single element of the array.
custom

Custom Fields of the ShoppingListLineItem.

Example: json
{
  "id": "ade85d60-736b-4ca8-87ed-01fde78f92c5",
  "productId": "077bb11b-0d00-4e00-aced-48f493a79da0",
  "published": true,
  "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.
MinLength2MaxLength256Pattern^[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
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.

Default1Minimum1
custom

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.
MinLength2MaxLength256Pattern^[a-zA-Z0-9_-]
addedAt
Date and time (UTC) the TextLineItem was added to the ShoppingList.
description

Description of the TextLineItem.

name

Name of the TextLineItem.

quantity
Int

Number of entries in the TextLineItem.

custom

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.
MinLength2MaxLength256Pattern^[a-zA-Z0-9_-]
addedAt
Date and time the TextLineItem is added to the ShoppingList. If not set, the current date and time (UTC) is used.
description

Description of the TextLineItem.

name

Name of the TextLineItem.

quantity
Int

Number of entries in the TextLineItem.

Default1Minimum1
custom

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}
Retrieves a ShoppingList with the provided 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Retrieves a ShoppingList with the provided 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Retrieves a ShoppingList with the provided id in a Store. 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Retrieves a ShoppingList with the provided key in a Store. 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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

Retrieves ShoppingLists in the Project.

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
The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
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
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
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
var.<varName>
String
The parameter can be passed multiple times.
Response:
200

ShoppingListPagedQueryResponse

as
application/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": [],
      "businessUnit": {
        "key": "bu-345-france",
        "typeId": "business-unit"
      },
      "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
Retrieves ShoppingLists in a Store.
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
The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
Limitation: expand=lineItems[0].variant and expand=lineItems[0].productSlug are not supported.
The parameter can be passed multiple times.
limit
Int
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
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
var.<varName>
String
The parameter can be passed multiple times.
Response:
200

ShoppingListPagedQueryResponse

as
application/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": [],
      "businessUnit": {
        "key": "bu-345-france",
        "typeId": "business-unit"
      },
      "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 with the provided id. Returns a 200 status if the ShoppingList exists, or a 404 status 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 with the provided key. Returns a 200 status if the ShoppingList exists, or a 404 status 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 one or more ShoppingLists exist for the provided query predicate. Returns a 200 status if any ShoppingLists match the query predicate, or a 404 status 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
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 with the provided id in a Store. Returns a 200 status if the ShoppingList exists, or a 404 status 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 with the provided key in a Store. Returns a 200 status if the ShoppingList exists, or a 404 status 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 one or more ShoppingLists exist for the provided query predicate in a Store. Returns a 200 status if any ShoppingLists match the query predicate or, or a 404 status 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
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

Create a ShoppingList in the Project.

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
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:
201

ShoppingList

as
application/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
  } ],
  "businessUnit" : {
    "key" : "bu-345-france",
    "typeId" : "business-unit"
  }
}
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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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
Creates a ShoppingList in a Store. 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
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:
201

ShoppingList

as
application/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
  } ],
  "businessUnit" : {
    "key" : "bu-345-france",
    "typeId" : "business-unit"
  }
}
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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Updates a ShoppingList in the Project using one or more update actions.
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
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

List of update actions to be performed on the ShoppingList.

Response:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Updates a ShoppingList in the Project using one or more update actions.
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
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

List of update actions to be performed on the ShoppingList.

Response:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Updates a ShoppingList in a Store using one or more update actions. 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
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

List of update actions to be performed on the ShoppingList.

Response:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Updates a ShoppingList in a Store using one or more update actions. 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
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

List of update actions to be performed on the ShoppingList.

Response:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "deleteDaysAfterLastModification": 100,
  "createdAt": "2022-08-22T14:11:03.587Z",
  "lastModifiedAt": "2022-08-22T14:11:03.587Z"
}

Update actions

Set Key

action
String
"setKey"
key
String

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

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
Example: json
{
  "action": "setKey",
  "key": "new-shopping-list-key"
}

Set Slug

action
String
"setSlug"
slug
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

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

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
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
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 Business Unit B2B

Updates the Business Unit on the Shopping List. The Shopping List must have an existing Business Unit assigned already.

action
String
"setBusinessUnit"
businessUnit
The Business Unit to assign to the Shopping List, which must have access to the Store that is set on the Shopping List.
Example: json
{
  "action": "setBusinessUnit",
  "businessUnit": {
    "key": "{{business-unit-key}}",
    "typeId": "business-unit"
  }
}

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
Defines the Type that extends the ShoppingList with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShoppingList.
fields
Sets the Custom Fields fields for the ShoppingList.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action
String
"setCustomField"
name
String
Name of the Custom Field.
value
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": "exampleStringField",
  "value": "TextString"
}

Set DeleteDaysAfterLastModification

Number of days after the last modification before a Shopping List is deleted.

action
String
"setDeleteDaysAfterLastModification"
deleteDaysAfterLastModification
Int
Value to set. If not provided, the default value for this field configured in Project settings is assigned.
Minimum1Maximum365250
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.

Product Attributes are merged with Variant Attributes to ensure the full Attribute context of the Product Variant.

Produces the Shopping List Line Item Added Message.
action
String
"addLineItem"
key
String
User-defined identifier of the ShoppingListLineItem. Must be unique per ShoppingList.
MinLength2MaxLength256Pattern^[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.

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

Custom Fields defined for the ShoppingListLineItem.

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

Remove ShoppingListLineItem

Produces the Shopping List Line Item Removed Message.
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.
Minimum1
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.
Minimum0
Example: json
{
  "action": "changeLineItemQuantity",
  "lineItemId": "{{lineItemId}}",
  "quantity": 8
}

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

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
Defines the Type that extends the ShoppingListLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShoppingListLineItem.
fields
Sets the Custom Fields fields for the ShoppingListLineItem.
Example: json
{
  "action": "setLineItemCustomType",
  "lineItemId": "{{lineItemId}}",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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
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": "exampleStringField",
  "value": "TextString"
}

Update TextLineItems

Add TextLineItem

action
String
"addTextLineItem"
key
String
User-defined identifier of the TextLineItem. Must be unique per ShoppingList.
MinLength2MaxLength256Pattern^[a-zA-Z0-9_-]
name

Name of the TextLineItem.

description

Description of the TextLineItem.

quantity
Int

Number of entries in the TextLineItem.

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

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.
Minimum1
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.
Minimum0
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

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

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 ids 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
Defines the Type that extends the TextLineItem with Custom Fields. If absent, any existing Type and Custom Fields are removed from the TextLineItem.
fields
Sets the Custom Fields fields for the TextLineItem.
Example: json
{
  "action": "setTextLineItemCustomType",
  "textLineItemId": "{{lineItemId}}",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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
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": "exampleStringField",
  "value": "TextString"
}

Delete ShoppingList

Delete ShoppingList by ID

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

Deletes a ShoppingList in the Project.

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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}

Deletes a ShoppingList in the Project.

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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Deletes a ShoppingList in a Store. 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "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}
Deletes a ShoppingList in a Store. 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
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:
200

ShoppingList

as
application/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",
      "published": true,
      "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"
    }
  ],
  "businessUnit": {
    "key": "bu-345-france",
    "typeId": "business-unit"
  },
  "deleteDaysAfterLastModification": 100,
  "createdAt": "2022-08-22T14:11:03.587Z",
  "lastModifiedAt": "2022-08-22T14:11:03.587Z"
}