Retrieving and Applying Product Options
  • Updated on 04 Mar 2020
  • 11 minutes to read
  • Print
  • Share
  • Dark
    Light

Retrieving and Applying Product Options

  • Print
  • Share
  • Dark
    Light

The Product Options Feature enables shop owners to suggest various additions to the main product. Such extras enhance the customer experience and ensure their loyalty to the shop. These typically include gift wrapping, warranty services, insurance, app installation, etc.

Options come with their own prices and tax sets. Also, different options can apply to different products. All product options available in a shop are organized in groups.

Although options are applied to abstract products only, the Product Options API enables retrieving available options for both abstract and concrete products. Also, it enables selecting the necessary options when ordering products and viewing the selected options when an order is complete. For this purpose, product options are retrievable in endpoints related to products (e.g. /abstract-products or /concrete-products), guest carts and carts of registered users (e.g. /guest-cart-items or /carts/{{cart_id}}/items, etc.), as well as in order history.

With the help of the data provided by the API resources, you will be able to perform the following tasks:

  • retrieve product options available for any products;
  • enable customers to select the options they want when placing items in a cart;
  • display the selected options during checkout and in the order history.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see GLUE: Product Options Feature Integration.

Retrieving Product Options for Products

To retrieve the product options available for a specific product, send a GET request to retrieve the product information and include product-options as a relationship.

Request

Endpoints:

  • /abstract-products
  • /concrete-products

Sample request: GET http://glue.mysprykershop.com/concrete-products/181_31995510?include=product-options

where 181_31995510 is the SKU of the product you want to retrieve options for.

Response

The endpoints return information on the requested products. Product options are available in the product-options included section.

Response Attributes:
Each product option is represented by a related resource with the following attributes:

Attribute* Type Description
sku String Specifies the SKU of the product option.
optionName String Specifies the option name.
optionGroupName String Specifies the name of the group to which the option belongs.
price Integer Specifies the option price in cents.
currencyIsoCode String Specifies the ISO 4217 code of the currency in which the product option price is specified.
  • Type and ID are not mentioned.
Sample Response
{
    "data": {
        "type": "concrete-products",
        "id": "181_31995510",
        "attributes": {...},
        "links": {...},
        "relationships": {
            "product-options": {
                "data": [
                    {
                        "type": "product-options",
                        "id": "OP_1_year_waranty"
                    },
                    {
                        "type": "product-options",
                        "id": "OP_2_year_waranty"
                    },
                    {
                        "type": "product-options",
                        "id": "OP_3_year_waranty"
                    },
                    {
                        "type": "product-options",
                        "id": "OP_insurance"
                    },
                    {
                        "type": "product-options",
                        "id": "OP_gift_wrapping"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "type": "product-options",
            "id": "OP_1_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_1_year_waranty",
                "optionName": "One (1) year limited warranty",
                "price": 0,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_1_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_2_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_2_year_waranty",
                "optionName": "Two (2) year limited warranty",
                "price": 1000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_2_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_3_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_3_year_waranty",
                "optionName": "Three (3) year limited warranty",
                "price": 2000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_3_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_insurance",
            "attributes": {
                "optionGroupName": "Insurance",
                "sku": "OP_insurance",
                "optionName": "Two (2) year insurance coverage",
                "price": 10000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_insurance"
            }
        },
        {
            "type": "product-options",
            "id": "OP_gift_wrapping",
            "attributes": {
                "optionGroupName": "Gift wrapping",
                "sku": "OP_gift_wrapping",
                "optionName": "Gift wrapping",
                "price": 500,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_gift_wrapping"
            }
        }
    ]
}

Retrieving Product Options for Cart Items

To retrieve the product options available for items in a cart, send a GET request to retrieve the cart information and include the items/guest-cart-items, concrete-products, and product-options resources as relationships.

Note

Product option information is also available for POST and PATCH requests, which means that you can also retrieve product options when sending requests to create carts as well as adding or removing cart items. For example, you can fetch the options to display to the customer once a new product is added to a cart.

Request

Endpoints for carts of registered users:

  • /carts
  • /carts/{{cart_id}}
  • /carts/{{cart_id}}/items
  • /carts/{{cart_id}}/items/{{item_id}}
Authentication

Carts of registered users cannot be accessed anonymously. For this reason, you always need to pass a user's authentication token when accessing the endpoint. For details on how to authenticate a user and retrieve the token, see Authentication and Authorization.

Endpoints for guest carts:

  • /guest-cart-items
  • /guest-carts
  • /guest-carts/{{guest_cart_id}}
  • /guest-carts/{{guest_cart_id}}/guest-cart-items
  • /guest-carts/{{guest_cart_id}}/guest-cart-items/{{guest_cart_item_id}}
Anonymous User ID

When accessing guest carts, you need to specify the guest user ID. This is done via the X-Anonymous-Customer-Unique-Id header. Guest user IDs are managed by the API Client. For details, see Managing Guest Carts.

Sample requests:

GET http://glue.mysprykershop.com/carts?include=items,concrete-products,product-options

GET http://glue.mysprykershop.com/guest-carts/1ce91011-8d60-59ef-9fe0-4493ef3628b2/?include=guest-cart-items,concrete-products,product-options

POST http://glue.mysprykershop.com/guest-cart-items?include=guest-cart-items,concrete-products,product-option

PATCH http://glue.mysprykershop.com/carts/f9a3f045-02c2-5d47-b397-8ac1f5c63e27/items/181_31995510?include=guest-cart-items,concrete-products,product-option

Performance

The above requests fetch not only product option information, but also information on the products in the cart. That can adversely affect the overall performance. Use them with caution and apply caching, where possible.

Response

The API returns information on the requested carts, cart items and products. Product options are available in the product-options resource relationship.

If any product options have been selected when placing a product in the cart, they are specified in the selectedProductOptions attribute of the respective cart item. The attribute is an array.

Response Attributes:
Each selected option is specified in the selectedProductOptions attribute of the items or guest-cart-items resource relationship.

Attribute* Type Description
selectedProductOptions Array of product-options. Specifies the selected product options.

Each product option available for every product in the cart is represented by a related product-options resource with the following attributes:

Attribute* Type Description
sku String Specifies the SKU of the product option.
optionName String Specifies the option name.
optionGroupName String Specifies the name of the group to which the option belongs.
price Integer Specifies the option price in cents.
currencyIsoCode String Specifies the ISO 4217 code of the currency in which the product option price is specified.
  • Type and ID are not mentioned.
Sample Response - Guest Cart
{
    "data": {
        "type": "guest-carts",
        "id": "a460ac71-06ee-5018-b6d6-a2191d183f24",
        "attributes": {...},
        "links": {...},
        "relationships": {
            "guest-cart-items": {
                "data": [
                    {
                        "type": "guest-cart-items",
                        "id": "181_31995510-3-5"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "type": "guest-cart-items",
            "id": "181_31995510-3-5",
            "attributes": {
                "sku": "181_31995510",
                ...
                "selectedProductOptions": [
                    {
                        "optionGroupName": "Gift wrapping",
                        "sku": "OP_gift_wrapping",
                        "optionName": "Gift wrapping",
                        "price": 2000
                    },
                    {
                        "optionGroupName": "Warranty",
                        "sku": "OP_3_year_waranty",
                        "optionName": "Three (3) year limited warranty",
                        "price": 8000
                    }
                ]
            },
            "links": {
                "self": "http://glue.mysprykershop.com/guest-carts/a460ac71-06ee-5018-b6d6-a2191d183f24/guest-cart-items/181_31995510-3-5"
            },
            "relationships": {
                "concrete-products": {
                    "data": [
                        {
                            "type": "concrete-products",
                            "id": "181_31995510"
                        }
                    ]
                }
            },
        },
        {
            "type": "product-options",
            "id": "OP_1_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_1_year_waranty",
                "optionName": "One (1) year limited warranty",
                "price": 0,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_1_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_2_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_2_year_waranty",
                "optionName": "Two (2) year limited warranty",
                "price": 1000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_2_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_3_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_3_year_waranty",
                "optionName": "Three (3) year limited warranty",
                "price": 2000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_3_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_insurance",
            "attributes": {
                "optionGroupName": "Insurance",
                "sku": "OP_insurance",
                "optionName": "Two (2) year insurance coverage",
                "price": 10000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_insurance"
            }
        },
        {
            "type": "product-options",
            "id": "OP_gift_wrapping",
            "attributes": {
                "optionGroupName": "Gift wrapping",
                "sku": "OP_gift_wrapping",
                "optionName": "Gift wrapping",
                "price": 500,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_gift_wrapping"
            }
        },
        }
    ]
}

Sample Response - Cart of Registered User
{
    "data": [
        {
            "type": "carts",
            "id": "56a0b4e4-21d8-516f-acd5-90581c996676",
            "attributes": {...},
            "links": {...},
            "relationships": {
                "items": {
                    "data": [
                        {
                            "type": "items",
                            "id": "181_31995510"
                        },
                        {
                            "type": "items",
                            "id": "181_31995510-2-4-5"
                        },
                        {
                            "type": "items",
                            "id": "181_31995510"
                        },
                        {
                            "type": "items",
                            "id": "181_31995510-2-4-5"
                        }
                    ]
                }
            }
        }
    ],
    "links": {...},
    "included": [
        {
            "type": "items",
            "id": "181_31995510",
            "attributes": {
                "sku": "181_31995510",
                ...
                "selectedProductOptions": [
                    {
                        "optionGroupName": "Warranty",
                        "sku": "OP_2_year_waranty",
                        "optionName": "Two (2) year limited warranty",
                        "price": 4000
                    },
                    {
                        "optionGroupName": "Insurance",
                        "sku": "OP_insurance",
                        "optionName": "Two (2) year insurance coverage",
                        "price": 40000
                    },
                    {
                        "optionGroupName": "Gift wrapping",
                        "sku": "OP_gift_wrapping",
                        "optionName": "Gift wrapping",
                        "price": 2000
                    }
                ]
            },
            "links": {...},
            "relationships": {...}
        },
        {
            "type": "product-options",
            "id": "OP_1_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_1_year_waranty",
                "optionName": "One (1) year limited warranty",
                "price": 0,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_1_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_2_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_2_year_waranty",
                "optionName": "Two (2) year limited warranty",
                "price": 1000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_2_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_3_year_waranty",
            "attributes": {
                "optionGroupName": "Warranty",
                "sku": "OP_3_year_waranty",
                "optionName": "Three (3) year limited warranty",
                "price": 2000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_3_year_waranty"
            }
        },
        {
            "type": "product-options",
            "id": "OP_insurance",
            "attributes": {
                "optionGroupName": "Insurance",
                "sku": "OP_insurance",
                "optionName": "Two (2) year insurance coverage",
                "price": 10000,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_insurance"
            }
        },
        {
            "type": "product-options",
            "id": "OP_gift_wrapping",
            "attributes": {
                "optionGroupName": "Gift wrapping",
                "sku": "OP_gift_wrapping",
                "optionName": "Gift wrapping",
                "price": 500,
                "currencyIsoCode": "EUR"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/181_31995510/product-options/OP_gift_wrapping"
            }
        },
        ...
    ]
}

Applying Product Options to Cart Items

In order to apply various products to cart items, you need to specify the necessary options when sending POST requests for creating carts and adding items to them.

Request

Endpoints for carts of registered users:

  • /carts/{{cart_id}}/items

Sample Request:
POST /carts/{{cart_id}}/cart-items - adds an item to a cart.

Info

For more details on managing carts of registered users, see Managing Carts of Registered Users.

Request Body

{
    "data": {
        "type": "items",
        "attributes": {
        	"sku": "181_31995510",
        	"quantity": 6,
            "productOptions": [
            	{
            		"sku": "OP_gift_wrapping"
            	},
            	{
            		"sku": "OP_3_year_waranty"
            	}
            ]
        }
    }
}
Authentication

Carts of registered users cannot be accessed anonymously. For this reason, you always need to pass a user's authentication token when accessing the endpoint. For details on how to authenticate a user and retrieve the token, see Authentication and Authorization.

Endpoints for guest carts:

  • /guest-cart-items
  • /guest-carts/{{guest_cart_id}}/guest-cart-items

Sample Requests:

POST /guest-cart-items - creates a guest cart;

POST /guest-carts/{{cart_id}}/cart-items - adds an item to a guest cart.

Info

For more details on managing carts of registered users, see Managing Guest Carts.

Request Body

{
    "data": {
        "type": "guest-cart-items",
        "attributes": {
            "sku": "181_31995510",
            "quantity": "4",
            "productOptions": [
            	{
            		"sku": "OP_gift_wrapping"
            	},
            	{
            		"sku": "OP_3_year_waranty"
            	}
            ]
        }
    }
}
Anonymous User ID

When accessing guest carts, you need to specify the guest user ID. This is done via the X-Anonymous-Customer-Unique-Id header. Guest user IDs are managed by the API Client. For details, see Managing Guest Carts.

Request Attributes
No matter which type of cart is created or modified, the following attributes should be present in the request:

Attribute* Type Required Description
sku String yes Specifies the SKU of the product to add to the cart or to modify.
quantity Integer yes Specifies the number of products to be available in the cart.
productOptions Array of product-option no Specifies the product options to apply to the product.

Each option must be represented by a JSON object containing only 1 attribute: sku. It specifies the SKU of the option to apply.

Note: It is the responsibility of the API Client to track whether the selected items are compatible. For example, the client should not allow a 2-year and a 4-year warranty service to be applied to the same product. The API endpoints allow any combination of items, no matter whether they are compatible or not.

You can specify a certain product several times with different options. In this case, the product will be added as multiple cart items.

Response

The endpoints respond with information on the cart or item that is being created or modified. For detailed information and the possible error codes, see Managing Carts of Registered Users and Managing Guest Carts.

Retrieving Product Options for Orders

To retrieve the product options applied to order items, send a GET request to retrieve the order information.

Request

Endpoint: /orders/{{order_id}} - retrieves a specific order.

Authentication

Orders cannot be accessed anonymously. For this reason, you always need to pass a user's authentication token when accessing the endpoint. For details on how to authenticate a user and retrieve the token, see Authentication and Authorization.

Sample request: GET http://glue.mysprykershop.com/orders/DE--3

Tip

You can also receive product option information immediately after checkout id complete by including the necessary information in the checkout call: POST http://glue.mysprykershop.com/checkout?include=orders

Response

The endpoints return information on the requested order(s). If any product options have been selected when placing the order, they are specified in the productOptions attribute of the respective order item.

Response Attributes:
The options applied to the order are specified in the productOptions attribute of each element in the items array.

Attribute* Type Description
productOptions Array of product-option. Specifies the product options.

Sample response

{
    "data": {
        "type": "orders",
        "id": "DE--2",
        "attributes": {
            ...
            "items": [
                {
                    "name": "Acer Chromebook C730-C8T7",
                    "sku": "136_24425591",
                    ...
                    "productOptions": [
                        {
                            "optionGroupName": "Gift wrapping",
                            "sku": "OP_gift_wrapping",
                            "optionName": "Gift wrapping",
                            "price": 500
                        },
                        {
                            "optionGroupName": "Warranty",
                            "sku": "OP_2_year_waranty",
                            "optionName": "Two (2) year limited warranty",
                            "price": 1000
                        }
                    ]
                }
            ],
            ...
        "links": {...}
    }
}

For detailed information and the possible error codes, see Retrieving Customer's Order History.

Was this article helpful?