addDownloadableProductsToCart mutation

A downloadable product can be anything that you can deliver as a file, such as an eBook, music, video, software application, or an update. To add a downloadable product to a cart, you must provide the cart ID, the SKU, and the quantity. In some cases, you must include the IDs for downloadable product links. You can also optionally specify customizable options.

Syntax

1
2
3
4
5
6
7
mutation: {
    addDownloadableProductsToCart(
        input: AddDownloadableProductsToCartInput
    ): {
        AddDownloadableProductsToCartOutput
    }
}

Example usage

The following examples show how to add a downloadable product to a shopping cart , depending on whether the Links can be purchased separately option is selected on the Downloadable Information section of the product page.

The following example shows how to add a downloadable product in which the Links can be purchased separately option is enabled. The payload includes custom downloadable links Episode 2 and Episode 3.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
mutation {
  addDownloadableProductsToCart(
    input: {
      cart_id: "gMV2BFQuNGiQmTnepQlMGko7Xc4P3X1w"
      cart_items: {
        data: {
          sku: "240-LV09"
          quantity: 1
        }
        downloadable_product_links: [
          {
            link_id: 7                 # Episode 2
          }
          {
            link_id: 8                 # Episode 3
          }
        ]
      }
    }
  ) {
    cart {
      items {
        product {
          sku
        }
        quantity
        ... on DownloadableCartItem {
          links {
            title
            price
          }
          samples {
            title
            sample_url
          }
        }
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "data": {
    "addDownloadableProductsToCart": {
      "cart": {
        "items": [
          {
            "product": {
              "sku": "240-LV09"
            },
            "quantity": 1,
            "links": [
              {
                "title": "Episode 2",
                "price": 9
              },
              {
                "title": "Episode 3",
                "price": 9
              }
            ],
            "samples": [
              {
                "title": "Trailer #1",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/16/"
              },
              {
                "title": "Trailer #2",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/17/"
              },
              {
                "title": "Trailer #3",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/18/"
              }
            ]
          }
        ]
      }
    }
  }
}

The following example shows how to add a downloadable product in which the Links can be purchased separately option is disabled. All downloadable links are added to the cart automatically.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
mutation {
  addDownloadableProductsToCart(
    input: {
      cart_id: "gMV2BFQuNGiQmTnepQlMGko7Xc4P3X1w"
      cart_items: {
        data: {
          sku: "240-LV07"
          quantity: 1
        }
      }
    }
  ) {
    cart {
      items {
        product {
          sku
        }
        quantity
        ... on DownloadableCartItem {
          links {
            title
            price
          }
          samples {
            title
            sample_url
          }
        }
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "data": {
    "addDownloadableProductsToCart": {
      "cart": {
        "items": [
          {
            "product": {
              "sku": "240-LV07"
            },
            "quantity": 2,
            "links": [
              {
                "title": "Solo Power Circuit",
                "price": 14
              }
            ],
            "samples": [
              {
                "title": "Trailer #1",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/10/"
              },
              {
                "title": "Trailer #2",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/11/"
              },
              {
                "title": "Trailer #3",
                "sample_url": "https://<M2_INSTANCE>/downloadable/download/sample/sample_id/12/"
              }
            ]
          }
        ]
      }
    }
  }
}

Input attributes

The top-level AddDownloadableProductsToCartInput object is listed first. All child objects are listed in alphabetical order.

AddDownloadableProductsToCartInput object

The AddDownloadableProductsToCartInput object must contain the following attributes:

Attribute Data Type Description
cart_id String! The unique ID that identifies the customer’s cart
cart_items [DownloadableProductCartItemInput!]! Contains the cart item IDs and quantity of each item

CartItemInput object

The CartItemInput object must contain the following attributes:

Attribute Data Type Description
quantity Float! The quantity of the item to add to the cart
sku String! The sku of the product to be added to the cart

CustomizableOptionInput object

The CustomizableOptionInput object must contain the following attributes:

Attribute Data Type Description
id Int! A unique ID assigned to the customizable option
value_string String! A value assigned to the customizable option

DownloadableProductCartItemInput object

The DownloadableProductCartItemInput object can contain the following attribute:

Attribute Data Type Description
customizable_options [CustomizableOptionInput!] An array that defines customizable options for the product
data CartItemInput! Required. An object containing the sku and quantity of the product
downloadable_product_links [DownloadableProductLinksInput!] An object containing the link_id of the downloadable product link

DownloadableProductLinksInput object

If specified, the DownloadableProductLinksInput object must contain the following attribute.

Attribute Data Type Description
link_id Int! A unique ID (downloadable_link.link_id) of the downloadable product link

Output attributes

The AddDownloadableProductsToCartOutput object contains the Cart object.

Attribute Data Type Description
cart Cart! Describes the contents of the specified shopping cart

Cart object

Attribute Data Type Description
applied_coupon AppliedCoupon Deprecated. Use applied_coupons instead
applied_coupons [AppliedCoupon] An array of AppliedCoupon objects. Each object contains the code text attribute, which specifies the coupon code
applied_gift_cards [AppliedGiftCard] An array of AppliedGiftCard objects. An AppliedGiftCard object contains the code text attribute, which specifies the gift card code. applied_gift_cards is a Commerce-only attribute, defined in the GiftCardAccountGraphQl module
applied_store_credit AppliedStoreCredit Contains store credit information applied to the cart. applied_store_credit is a Commerce-only attribute, defined in the CustomerBalanceGraphQl module
available_payment_methods [AvailablePaymentMethod] Available payment methods
billing_address BillingCartAddress Contains the billing address specified in the customer’s cart
email String The customer’s email address
id ID! The ID of the cart
is_virtual Boolean Indicates whether the cart contains only virtual products
items [CartItemInterface] Contains the items in the customer’s cart
prices CartPrices Contains subtotals and totals
selected_payment_method SelectedPaymentMethod Selected payment method
shipping_addresses [ShippingCartAddress]! Contains one or more shipping addresses

Errors

Error Description
Required parameter "cart_id" is missing The mutation does not contain a cart_id parameter.
Required parameter "cart_items" is missing The cart_items parameter is empty or is not of type array.
Please specify product link(s). You tried to add a downloadable product in which the Links can be purchased separately option is enabled, but you did not specify individual product links.