Shopping Lists

Representations

All representations are JSON objects submitted or received as payload to API requests or responses.

ShoppingList

• id - String
  The unique ID of the Shopping List.
• key - String - Optional
  User-specific unique identifier for the Shopping List.
• version - Number
  The current version of the Shopping List.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• slug - LocalizedString - Optional
  Human-readable identifiers usually used as deep-link URL to the related Shopping List.
  Each slug is unique across a project, but a Shopping List 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.
• name - LocalizedString
• description - LocalizedString - Optional
• customer - Reference to a Customer - Optional
• anonymousId - String - Optional
  Identifies Shopping Lists belonging to an anonymous session (the customer has not signed up/in yet).
• store - KeyReference to a Store - Optional
• lineItems - Array of LineItem
• textLineItems - Array of TextLineItem
• custom - CustomFields - Optional
• deleteDaysAfterLastModification - Number - Optional
  The Shopping List will be deleted automatically if it hasn't been modified for the specified amount of days.

ShoppingListDraft

A ShoppingListDraft is the object submitted as payload to a Create a ShoppingList method.

• key - String - Optional
  User-specific unique identifier for the Shopping List.
• slug - LocalizedString - Optional
  Human-readable identifiers usually used as deep-link URL to the related Shopping List.
  Each slug is unique across a project, but a Shopping List can have the same slug for different languages. The slug must match the pattern [a-zA-Z0-9_\-]{2,256}.
• name - LocalizedString - Required
• description - LocalizedString - Optional
• customer - ResourceIdentifier of a Customer - Optional
• anonymousId - String - Optional
  Identifies Shopping Lists belonging to an anonymous session (the customer has not signed up/in yet).
• store - ResourceIdentifier of a Store - Optional
• lineItems - Array of LineItemDraft - Optional
• textLineItems - Array of TextLineItemDraft - Optional
• custom - CustomFieldsDraft - Optional
  The custom fields.
• deleteDaysAfterLastModification - Number - Optional
  The Shopping List will be deleted automatically if it hasn't been modified for the specified amount of days. If not set, the default value configured in the Project is used.

LineItem

A Line Item is a reference to a ProductVariant in a Product in its current version.

• id - String
  The unique Id of this LineItem.
• productId - String
  ID of an existing Product.
• variantId - Number - Optional
  If present it defines an existing ProductVariant of the product.
  If absent it refers to the current master variant of the product.
• productType - Reference to a ProductType
  Refers to the product type of the product.
• quantity - Number
• custom - CustomFields - Optional
• addedAt - DateTime When the Line Item was added to the Shopping List.
• name - LocalizedString
  Name of the product.
  This data is updated in an eventual consistent manner when the product's name changes.
• deactivatedAt - DateTime - Optional
  If the product or product variant cannot be purchased anymore, deactivatedAt is set to the date of the deactivation.
  A Line Item with a deactivatedAt datetime can be displayed to the user as automatically deleted.
  This data is updated in an eventual consistent manner when the product variant cannot be ordered anymore.

In addition to the standard reference expansion, a Line Item offers custom expansions (also defined with the query parameter expand).
When using those custom expansion, the following fields are available:

• productSlug- LocalizedString - Optional
  Slug of the current ProductData, activated by expand=lineItems[*].productSlug.
  limitation: expand=lineItems[0].productSlug is not supported
• variant- ProductVariant - Optional
  Current product variant, activated by expand=lineItems[*].variant
  limitation: expand=lineItems[0].variant is not supported

LineItemDraft Product Variant identification

The product variant to be selected in the LineItemDraft can be specified either by its product ID plus variant ID or by its SKU.
Choose one of the options below:

Selection by IDs

• productId - String - Required
  ID of an existing Product.
• variantId - Number - Optional
  If present it defines an existing ProductVariant of the product. If absent it refers to the current master variant of the product.

Selection by SKU

• sku - String - Required
  SKU of an existing ProductVariant.

LineItemDraft

• LineItemDraft Product Variant identification - Required
• quantity - Number - Optional
  Defaults to 1.
• addedAt - DateTime - Optional
  Defaults to the current date and time.
• custom - CustomFieldsDraft - Optional The custom fields.

TextLineItem

• id - String
  The unique ID of this TextLineItem.
• name - LocalizedString
• description - LocalizedString - Optional
• quantity - Number
• custom - CustomFields - Optional
• addedAt - DateTime
  When the text Line Item was added to the Shopping List.

TextLineItemDraft

• name - LocalizedString - Required
• description - LocalizedString - Optional
• quantity - Number - Optional
  Defaults to 1.
• addedAt - DateTime - Optional
  Defaults to the current date and time.
• custom - CustomFieldsDraft - Optional The custom fields.

Get a ShoppingList

Get a ShoppingList by ID

Gets a Shopping List by ID.

Endpoint: /{projectKey}/shopping-lists/{id}
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}
Response Representation: ShoppingList

Get a ShoppingList by Key

Gets a Shopping List by Key.

Endpoint: /{projectKey}/shopping-lists/key={key}
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}
Response Representation: ShoppingList

Get a ShoppingList in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/{id}
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList

Returns a Shopping List by its ID from a specific Store. The {storeKey} path parameter maps to a Store's key.

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

Get a ShoppingList in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList

Returns a Shopping List by its Key from a specific Store. The {storeKey} path parameter maps to a Store's key.

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

Query ShoppingLists

Endpoint: /{projectKey}/shopping-lists
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ShoppingList
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Query ShoppingLists in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists
Method: GET
OAuth 2.0 Scopes: view_shopping_lists:{projectKey}, view_shopping_lists:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of ShoppingList
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Queries Shopping Lists in a specific Store. The {storeKey} path parameter maps to a Store's key.

Create a ShoppingList

Endpoint: /{projectKey}/shopping-lists
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}
Request Representation: ShoppingListDraft
Response Representation: ShoppingList

Create a ShoppingList in a Store

Creates a ShoppingList in a specific Store. The {storeKey} path parameter maps to a Store's key.

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

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Request Representation: ShoppingListDraft
Response Representation: ShoppingList

Update a ShoppingList

Update a ShoppingList by ID

Endpoint: /{projectKey}/shopping-lists/{id}
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}
Response Representation: ShoppingList
Fields:

• version - Number - Required
  The expected version of the Shopping List on which the changes should be applied. If the expected version does not match the actual version, a Conflict (409) will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the Shopping List.

Update a ShoppingList in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/{id}
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList
Fields:

• version - Number - Required
  The expected version of the Shopping List on which the changes should be applied. If the expected version does not match the actual version, a Conflict (409) will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the Shopping List.

Updates a Shopping List in the Store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

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

Update a ShoppingList by Key

Update a Shopping List found by its Key.

Endpoint: /{projectKey}/shopping-lists/key={key}
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}
Response Representation: ShoppingList
Fields:

• version - Number - Required
  The expected version of the Shopping List on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the Shopping List.

Update a ShoppingList in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}
Method: POST
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList
Fields:

• version - Number - Required
  The expected version of the Shopping List on which the changes should be applied. If the expected version does not match the actual version, a Conflict (409) will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the Shopping List.

Updates a Shopping List in the Store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

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

Update actions

Set Key

• action - String - "setKey"
• key - String - Optional
  If key is absent or null, the existing key, if any, will be removed.

Set Slug

• action - String - "setSlug"
• slug - LocalizedString - Optional

Change Name

• action - String - "changeName"
• name - LocalizedString - Required

Set Description

• action - String - "setDescription"
• description - LocalizedString - Optional

Set Customer

• action - String - "setCustomer"
• customer - ResourceIdentifier of a Customer - Optional

Set Store

• action - String - "setStore"
• store - ResourceIdentifier of a Store - Optional

Set AnonymousID

Sets an anonymous ID that corresponds to a customer who has authenticated with an anonymous session.

• action - String - "setAnonymousId"
• anonymousId - String - Optional
  Anonymous ID of the anonymous customer that this Shopping List belongs to. If this field is not set any existing anonymousId is removed.

Set Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing Shopping List.

• action - String - "setCustomType"
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is set to this new value. If absent, the custom type and any existing custom fields are removed.
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  If set, the custom fields are set to this new value.

Set CustomField

This action sets, overwrites, or removes any existing custom field for an existing Shopping List.

UpdateAction on Line Item

Add LineItem

Adds a Line Item for a product variant to the Shopping List.
If the Shopping List already contains a Line Item for the same product variant with the same custom fields, then only the quantity of existing the LineItem is increased.
a Line Item with an empty variant ID is not considered the same as a Line Item with a variant ID currently referring the master variant

• action - String - "addLineItem"
• LineItemDraft - Required

Remove LineItem

Decreases the quantity of the given LineItem.
If the quantity is absent or the updated quantity is less than 1, the Line Item is removed from the Shopping List.

• action - String - "removeLineItem"
• lineItemId - String - Required
  ID of an existing LineItem in the Shopping List.
• quantity - Number - Optional

Change LineItem Quantity

Sets the quantity of the given LineItem.
If quantity is 0, the Line Item is removed from the Shopping List.

• action - String - "changeLineItemQuantity"
• lineItemId - String - Required
  ID of an existing LineItem in the Shopping List.
• quantity - Number - Required

Change LineItems Order

• action - String - "changeLineItemsOrder"
• lineItemOrder - Array of String - Required
  lineItemOrder must contain all existing Line Item IDs in the desired new order.

Set LineItem Custom Type

This action sets, overwrites, or removes the custom type and fields for an existing LineItem.

• action - String - "setLineItemCustomType"
• lineItemId - String - Required
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is set to this new value. If absent, the custom type and any existing CustomFields are removed at the same time.
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  If set, the custom fields are set to this new value.

Set LineItem CustomField

This action sets, overwrites, or removes any existing custom field for an existing LineItem.

• action - String - "setLineItemCustomField"
• lineItemId - String - Required
• name - String - Required
• value - Value - Optional
  If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

UpdateAction on TextLineItem

Add TextLineItem

• action - String - "addTextLineItem"
• name - LocalizedString - Required
• description - LocalizedString - Optional
• quantity - Number - Optional
  Defaults to 1.
• addedAt - DateTime - Optional
  Defaults to the current date and time.
• custom - CustomFieldsDraft - Optional
  The custom fields.

Remove TextLineItem

Decreases the quantity of the given TextLineItem.
If after the update the quantity of the text Line Item is not greater than 0 or the quantity is not specified, the text Line Item is removed from the Shopping List.

• action - String - "removeTextLineItem"
• textLineItemId - String - Required
  ID of an existing TextLineItem in the Shopping List.
• quantity - Number - Optional

Change TextLineItem Quantity

Sets the quantity of the given TextLineItem.
If quantity is 0, the text Line Item is removed from the Shopping List.

• action - String - "changeTextLineItemQuantity"
• textLineItemId - String - Required
  ID of an existing TextLineItem in the Shopping List.
• quantity - Number - Required

Change TextLineItem Name

• action - String - "changeTextLineItemName"
• textLineItemId - String - Required
  ID of an existing TextLineItem in the Shopping List.
• name - LocalizedString - Required

Set TextLineItem Description

• action - String - "setTextLineItemDescription"
• textLineItemId - String - Required
  ID of an existing TextLineItem in the Shopping List.
• description - LocalizedString - Optional

Change TextLineItems Order

• action - String - "changeTextLineItemsOrder"
• textLineItemOrder - Array of String - Required
  textLineItemOrder must contain all existing text Line Item Ids in the desired new order.

Set TextLineItems Custom Type

This action sets, overwrites, or removes the custom type and fields for an existing TextLineItem.

• action - String - "setTextLineItemCustomType"
• textLineItemId - String - Required
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is set to this new value. If absent, the custom type and any existing CustomFields are removed at the same time.
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  If set, the custom fields are set to this new value.

Set TextLineItems CustomField

This action sets, overwrites, or removes any existing custom field for an existing TextLineItem.

• action - String - "setTextLineItemCustomField"
• textLineItemId - String - Required
• name - String - Required
• value - Value - Optional
  If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set DeleteDaysAfterLastModification

Sets deleteDaysAfterLastModification. The Shopping List will be deleted automatically if it hasn't been modified for the specified amount of days.

• action - String - "setDeleteDaysAfterLastModification"
• deleteDaysAfterLastModification - Number - Optional

Delete a ShoppingList

Delete a ShoppingList by ID

Delete a ShoppingList found by its ID.

Endpoint: /{projectKey}/shopping-lists/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}
Response Representation: ShoppingList
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false.

Delete a ShoppingList in a Store by ID

Delete a ShoppingList found by its ID in a specific Store. The {storeKey} path parameter maps to a Store's key.

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Delete a ShoppingList by Key

Delete a ShoppingList found by its Key.

Endpoint: /{projectKey}/shopping-lists/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}
Response Representation: ShoppingList
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Delete a ShoppingList in a Store by Key

Delete a ShoppingList found by its Key in a specific Store. The {storeKey} path parameter maps to a Store's key.

Endpoint: /{projectKey}/in-store/key={storeKey}/shopping-lists/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_shopping_lists:{projectKey}, manage_shopping_lists:{projectKey}:{storeKey}
Response Representation: ShoppingList
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false