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 hold line items of products in the platform or any other items that can be described as text.

A shopping list can contain up to 100 line items and and up to 100 text line items.

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
  • lastModifiedAt - DateTime
  • 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
  • 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).
  • 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 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 to a Customer - Optional
  • anonymousId - String - Optional
    Identifies shopping lists belonging to an anonymous session (the customer has not signed up/in yet).
  • 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.

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 Selection

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

LineItemDraft

TextLineItem

TextLineItemDraft

Get ShoppingList

Get ShoppingList by Id

Gets a shopping list by Id.

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

Get ShoppingList by Key

Gets a shopping list by Key.

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

Query ShoppingLists

Endpoint: /{projectKey}/shopping-lists
Method: GET
OAuth2 Scopes: view_shopping_lists:{projectKey}
Response Representation: PagedQueryResult with the results array of ShoppingList
Query Parameters:

Create ShoppingList

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

Update ShoppingList

Update ShoppingList by Id

Endpoint: /{projectKey}/shopping-lists/{id}
Method: POST
OAuth2 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 ShoppingList by Key

Update a shopping list found by its Key.

Endpoint: /{projectKey}/shopping-lists/key={key}
Method: POST
OAuth2 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 Actions
Please find below the individual update actions provided on this endpoint.


Set Key

  • action - String - "setKey"
  • key - String - Optional
    User-specific unique identifier for the shopping list.

Set Slug

Change Name

Set Description

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

Set Customer

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 to 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"
  • 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.
  • quantity - Number - Optional
    Defaults to 1.
  • addedAt - DateTime - Optional
    Defaults to the current date and time.
  • custom - CustomFieldsDraft - Optional The custom fields.

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

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

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 ShoppingList

Delete ShoppingList by Id

Delete a ShoppingList found by its Id.

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

  • version - Number - Required

Delete ShoppingList by Key

Delete a ShoppingList found by its Key.

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

  • version - Number - Required