Glue API: Retrieve alternative products

Last updated:
Edit on GitHub

The Alternative Products feature allows customers to find a substitute for a product that runs out of stock or is no longer available for other reasons. The feature is particularly useful when a certain product becomes discontinued. In this case, customers usually look for an up-to-date generation of the same product, and suggesting possible alternatives is crucial. For more details, see Alternative Products and Discontinued Products.

The Product Alternatives API provides access to alternative products via REST API requests. In particular, you can:

  • Find out whether a concrete product is discontinued.
  • Retrieve a list of alternative products of a product.

In your development, the endpoints help to:

  • Provide alternatives for a product that runs out or unavailable, for example, due to local restrictions.
  • Provide alternatives if a product is discontinued.
  • Make alternative products available to customers in their shopping list or suggestions area to make searching and comparing similar products easier.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Install the Alternative Products Glue API.

Check if a product is discontinued

Before suggesting an alternative product, check if a product is discontinued by retrieving a concrete product.

It is the responsibility of the client to identify if a product is unavailable and when to provide alternatives. The API only provides information on availability, discontinued status and possible alternatives.

Retrieve abstract alternative products

To retrieve abstract alternative products, send the request:

GET /concrete-products/{{concrete_product_sku}}/abstract-alternative-products

PATH PARAMETER DESCRIPTION
{{concrete_product_sku}} SKU of a concrete product to get abstract alternative products of.

Request

STRING PARAMETER DESCRIPTION EXEMPLARY VALUES
include Adds resource relationships to the request. product-labels
REQUEST USAGE
GET http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/abstract-alternative-products Retrieve abstract product alternatives of the product with SKU 145_29885470.
GET http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/abstract-alternative-products?include=product-labels Retrieve general information about the abstract product with its assigned product labels included.

Response

Response sample: retrieve abstract product alternatives of the product 
{
    "data": [
        {
            "type": "abstract-products",
            "id": "cable-hdmi-1",
            "attributes": {
                "sku": "cable-hdmi-1",
                "averageRating": null,
                "reviewCount": 0,
                "name": "HDMI cable",
                "description": "Enjoy clear, crisp, immediate connectivity with the High-Speed HDMI Cable. This quality High-Definition Multimedia Interface (HDMI) cable allows you to connect a wide variety of devices in the realms of home entertainment, computing, gaming, and more to your HDTV, projector, or monitor. Perfect for those that interact with multiple platforms and devices, you can rely on strong performance and playback delivery when it comes to your digital experience.",
                "attributes": [],
                "superAttributesDefinition": [],
                "superAttributes": {
                    "packaging_unit": [
                        "As long as you want",
                        "Ring"
                    ]
                },
                "attributeMap": {
                    "product_concrete_ids": [
                        "cable-hdmi-1-1",
                        "cable-hdmi-1-2"
                    ],
                    "super_attributes": {
                        "packaging_unit": [
                            "As long as you want",
                            "Ring"
                        ]
                    },
                    "attribute_variants": {
                        "packaging_unit:As long as you want": {
                            "id_product_concrete": "cable-hdmi-1-2"
                        },
                        "packaging_unit:Ring": {
                            "id_product_concrete": "cable-hdmi-1-1"
                        }
                    }
                },
                "metaTitle": "",
                "metaKeywords": "",
                "metaDescription": "",
                "attributeNames": {
                    "packaging_unit": "Packaging unit"
                },
                "url": "/en/hdmi-cable-1"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/abstract-products/cable-hdmi-1"
            }
        }
    ],
    "links": {
        "self": "http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/abstract-alternative-products"
    }
}
Response sample: retrieve abstract product alternatives of the product with the details on the product labels 
{
    "data": [
        {
            "type": "abstract-products",
            "id": "cable-hdmi-1",
            "attributes": {
                "sku": "cable-hdmi-1",
                "averageRating": null,
                "reviewCount": 0,
                "name": "HDMI cable",
                "description": "Enjoy clear, crisp, immediate connectivity with the High-Speed HDMI Cable. This quality High-Definition Multimedia Interface (HDMI) cable allows you to connect a wide variety of devices in the realms of home entertainment, computing, gaming, and more to your HDTV, projector, or monitor. Perfect for those that interact with multiple platforms and devices, you can rely on strong performance and playback delivery when it comes to your digital experience.",
                "attributes": [],
                "superAttributesDefinition": [],
                "superAttributes": {
                    "packaging_unit": [
                        "As long as you want",
                        "Ring"
                    ]
                },
                "attributeMap": {
                    "product_concrete_ids": [
                        "cable-hdmi-1-1",
                        "cable-hdmi-1-2"
                    ],
                    "super_attributes": {
                        "packaging_unit": [
                            "As long as you want",
                            "Ring"
                        ]
                    },
                    "attribute_variants": {
                        "packaging_unit:As long as you want": {
                            "id_product_concrete": "cable-hdmi-1-2"
                        },
                        "packaging_unit:Ring": {
                            "id_product_concrete": "cable-hdmi-1-1"
                        }
                    }
                },
                "metaTitle": "",
                "metaKeywords": "",
                "metaDescription": "",
                "attributeNames": {
                    "packaging_unit": "Packaging unit"
                },
                "url": "/en/hdmi-cable-1"
            },
            "links": {
                "self": "http://glue.mysprykershop.com/abstract-products/cable-hdmi-1"
            },
            "relationships": {
                "product-labels": {
                    "data": [
                        {
                            "type": "product-labels",
                            "id": "3"
                        }
                    ]
                }
            }
        }
    ],
    "links": {
        "self": "http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/abstract-alternative-products?include=product-labels"
    },
    "included": [
        {
            "type": "product-labels",
            "id": "3",
            "attributes": {
                "name": "New product",
                "isExclusive": false,
                "position": 1,
                "frontEndReference": null
            },
            "links": {
                "self": "http://glue.mysprykershop.com/product-labels/3"
            }
        }
    ]
}

Retrieve concrete alternative products

To retrieve concrete alternative products, send the request:

GET/concrete-products/{{concrete_product_sku}}/concrete-alternative-products

PATH PARAMETER DESCRIPTION
{{concrete_product_sku}} SKU of a concrete product to get concrete alternative products of.

Request

STRING PARAMETER DESCRIPTION EXEMPLARY VALUES
include Adds resource relationships to the request. product-labels
REQUEST USAGE
GET http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/concrete-alternative-products Retrieve concrete product alternatives of the product with SKU 145_29885470.
GET http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/concrete-alternative-products?include=product-labels Retrieve concrete product alternatives with the assigned product labels included.

Response

Response sample: retrieve concrete product alternatives of the product 
{
    "data": [
        {
            "type": "concrete-products",
            "id": "cable-hdmi-1-2",
            "attributes": {
                "sku": "cable-hdmi-1-2",
                "isDiscontinued": false,
                "discontinuedNote": null,
                "averageRating": null,
                "reviewCount": 0,
                "name": "HDMI cable as long as you want",
                "description": "Enjoy clear, crisp, immediate connectivity with the High-Speed HDMI Cable. This quality High-Definition Multimedia Interface (HDMI) cable allows you to connect a wide variety of devices in the realms of home entertainment, computing, gaming, and more to your HDTV, projector, or monitor. Perfect for those that interact with multiple platforms and devices, you can rely on strong performance and playback delivery when it comes to your digital experience.",
                "attributes": {
                    "packaging_unit": "As long as you want"
                },
                "superAttributesDefinition": [
                    "packaging_unit"
                ],
                "metaTitle": "",
                "metaKeywords": "",
                "metaDescription": "",
                "attributeNames": {
                    "packaging_unit": "Packaging unit"
                }
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/cable-hdmi-1-2"
            }
        }
    ],
    "links": {
        "self": "http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/concrete-alternative-products"
    }
}
Response sample: retrieve concrete product alternatives of the product with the details on the product labels 
{
    "data": [
        {
            "type": "concrete-products",
            "id": "cable-hdmi-1-2",
            "attributes": {
                "sku": "cable-hdmi-1-2",
                "isDiscontinued": false,
                "discontinuedNote": null,
                "averageRating": null,
                "reviewCount": 0,
                "name": "HDMI cable as long as you want",
                "description": "Enjoy clear, crisp, immediate connectivity with the High-Speed HDMI Cable. This quality High-Definition Multimedia Interface (HDMI) cable allows you to connect a wide variety of devices in the realms of home entertainment, computing, gaming, and more to your HDTV, projector, or monitor. Perfect for those that interact with multiple platforms and devices, you can rely on strong performance and playback delivery when it comes to your digital experience.",
                "attributes": {
                    "packaging_unit": "As long as you want"
                },
                "superAttributesDefinition": [
                    "packaging_unit"
                ],
                "metaTitle": "",
                "metaKeywords": "",
                "metaDescription": "",
                "attributeNames": {
                    "packaging_unit": "Packaging unit"
                }
            },
            "links": {
                "self": "http://glue.mysprykershop.com/concrete-products/cable-hdmi-1-2"
            },
            "relationships": {
                "product-labels": {
                    "data": [
                        {
                            "type": "product-labels",
                            "id": "3"
                        }
                    ]
                }
            }
        }
    ],
    "links": {
        "self": "http://glue.mysprykershop.com/concrete-products/cable-vga-1-1/concrete-alternative-products?include=product-labels"
    },
    "included": [
        {
            "type": "product-labels",
            "id": "3",
            "attributes": {
                "name": "New product",
                "isExclusive": false,
                "position": 1,
                "frontEndReference": null
            },
            "links": {
                "self": "http://glue.mysprykershop.com/product-labels/3"
            }
        }
    ]
}
RESOURCE ATTRIBUTE TYPE DESCRIPTION
abstract-products sku String SKU of the abstract product.
abstract-products averageRating String Average rating of the product based on customer rating.
abstract-products reviewCount Integer Number of reviews left by customer for this abstract product.
abstract-products name String Name of the abstract product.
abstract-products description String Description of the abstract product.
abstract-products attributes Object List of attributes and their values.
abstract-products superAttributeDefinition String Attributes flagged as super attributes that are, however, not relevant to distinguish between the product variants.
abstract-products attributeMap Object Each super attribute / value combination and the corresponding concrete product IDs are listed here.
abstract-products attributeMap.super_attributes Object Applicable super attribute and its values for the product variants.
abstract-products attributeMap.attribute_variants Object List of super attributes with the list of values.
abstract-products attributeMap.product_concrete_ids String Product IDs of the product variants.
abstract-products metaTitle String Meta title of the product.
abstract-products metaKeywords String Meta keywords of the product.
abstract-products metaDescription String Meta description of the product.
abstract-products attributeNames Object All non-super attribute / value combinations for the abstract product.
RESOURCE ATTRIBUTE TYPE DESCRIPTION
product-labels name String Specifies the label name.
product-labels isExclusive Boolean Indicates whether the label is exclusive.
If the attribute is set to true, the current label takes precedence over other labels the product might have. This means that only the current label should be displayed for the product, and all other possible labels should be hidden.
product-labels position Integer Indicates the label priority.
Labels should be indicated on the frontend according to their priority, from the highest (1) to the lowest, unless a product has a label with the isExclusive attribute set.
product-labels frontEndReference String Specifies the label custom label type (CSS class).
If the attribute is an empty string, the label should be displayed using the default CSS style.
RESOURCE ATTRIBUTE TYPE DESCRIPTION
concrete-products sku String SKU of the concrete product.
concrete-products isDiscontinued Boolean Specifies whether a product is discontinued:
true - the product is discontinued and requires a replacement item;
false—the product is not discontinued.
concrete-products discontinuedNote String Optional note that was specified when marking a product as discontinued.
concrete-products averageRating String Average rating of the product based on customer rating.
concrete-products reviewCount Integer Number of reviews left by customer for this product.
concrete-products name String Name of the concrete product.
concrete-products description String Description of the concrete product.
concrete-products attributes Object List of attribute keys and their values for the product.
concrete-products superAttributeDefinition String List of attributes that are flagged as super attributes.
concrete-products metaTitle String Meta title of the product.
concrete-products metaKeywords String Meta keywords of the product.
concrete-products metaDescription String Meta description of the product.
concrete-products attributeNames String List of attribute keys and their translations.
concrete-products productAbstractSku String Unique identifier of the abstract product owning this concrete product.

Possible errors

CODE REASON
302 Concrete product is not found.
312 Concrete product is ID not specified.

To view generic errors that originate from the Glue Application, see Reference information: GlueApplication errors.