openapi: 3.0.3 info: version: 2.0.0 title: Back-Off to Hero x-logo: url: https://www.ikea.com/ph/en/static/ikea-logo.f7d9229f806b59ec64cb.svg description: > ## What is it? The Back-Off to Hero API provides Product information to any IKEA API consumer with additional Back-Off or Hero attributes for IKEA Products contained within the IKEA Knowledge Graph ## How to get access? To request access to the API and Documentation about it's design send an email to [ikea.knowledge.graph@inter.ikea.com](mailto:ikea.knowledge.graph@inter.ikea.com) with any questions We also accept requests for new features
contact: email: ikea.knowledge.graph@inter.ikea.com servers: - url: https://knowledge-dev.api.inter.ikea.net/cbr/rosd/ikg/dev/api/back-off-to-hero/v2 description: Development environment x-environment: dev - url: https://knowledge-stage.api.inter.ikea.net/cbr/rosd/ikg/test/api/back-off-to-hero/v2 description: Staging environment x-environment: stage - url: https://knowledge.api.inter.ikea.net/cbr/rosd/ikg/api/back-off-to-hero/v2 description: Production environment x-environment: prod tags: - name: Products description: API Endpoints related to Product Back-Off and Hero properties in the Graph - name: Back-Off Products description: API Endpoints related only to Products marked as Back-Off Products - name: Hero Products description: API Endpoints related only to Products marked as Hero Products security: - SubscriptionKey: [] paths: /products/{itemNo}: get: tags: - Products summary: Get Graph Product by Item Number description: > This endpoint takes an `itemNo` of a Product contained within the Knowledge Graph and returns a `BackOffToHeroProduct` which contains additional properties. If the item is neither Back-Off nor Hero an empty object will be returned operationId: getProductById parameters: - in: path name: itemNo description: The `itemNo` or the the IKEA Product in the Graph schema: type: string example: "12345678" required: true - in: query name: fields description: >- A comma (`,`) seperated list of back-off product or hero product fields that we want the response to contain schema: type: string style: form explode: false example: itemNo,protectedBy,upsellArguments required: false - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- Returns a `BackOffToHeroProduct` Object, or an empty object if it is neither a back-off nor a hero product content: application/json: schema: $ref: "#/components/schemas/BackOffToHeroProduct" examples: Full Back-Off Product: value: itemType: ART itemNo: "12345678" itemName: "Product item Name" retailUnits: - se - nl strategicPricingRole: back-off protectsHero: - itemNo: "12345699" retailUnits: - se - nl - itemNo: "12345777" retailUnits: - se - nl protectedBy: [] upsellArguments: [] Full Hero Product: value: itemType: ART itemNo: "12345699" itemName: "Product item Name" retailUnits: - se strategicPricingRole: hero protectsHero: [] protectedBy: - itemNo: "12345678" retailUnits: - se upsellArguments: - shortText: Is more configurable longText: This product comes with more configuration options - shortText: Sustainable longText: This product is made from more sustainable products - shortText: 1 Year Guarentee longText: This product comes with a 1 Year Guarentee With Filter Value - Back-Off Product: value: protectsHero: - itemNo: "12345699" retailUnits: - se - itemNo: "12345777" retailUnits: - se With Filter Value - Hero Product: value: protectedBy: - itemNo: "12345678" retailUnits: - se upsellArguments: - shortText: Is more configurable longText: This product comes with more configuration options - shortText: Sustainable longText: This product is made from more sustainable products - shortText: 1 Year Guarentee longText: This product comes with a 1 Year Guarentee "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /products/heroes: get: tags: - Hero Products summary: Get All Graph Hero Products description: >- Returns an array that contains all Hero products from the Graph operationId: getHeroProducts parameters: - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- An array of Products that are Hero Products with Strategic Pricing, Hero and Back-Off properties content: application/json: schema: type: array items: $ref: "#/components/schemas/BackOffToHeroProduct" example: - itemType: ART itemNo: "12345678" itemName: "Product item Name" retailUnits: - se - nl strategicPricingRole: hero protectsHero: [] protectedBy: - itemNo: "97531246" retailUnits: - se - nl upsellArguments: - shortText: Is more configurable longText: This product comes with more configuration options - shortText: Sustainable longText: This product is made from more sustainable products - shortText: 1 Year Guarentee longText: This product comes with a 1 Year Guarentee - itemType: ART itemNo: "12345690" itemName: "Product item Name" retailUnits: - se strategicPricingRole: hero protectsHero: [] protectedBy: - itemNo: "97531246" retailUnits: - se upsellArguments: - shortText: Is more configurable longText: This product comes with more configuration options - shortText: Sustainable longText: This product is made from more sustainable products - shortText: 1 Year Guarentee longText: This product comes with a 1 Year Guarentee "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /products/heroes/item-numbers: get: tags: - Hero Products summary: Get All Hero Product `itemNo` description: Returns an array of all Graph Hero Product `itemNo` property operationId: getHeroItemNumbers parameters: - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- An array of string values that are the `itemNo` of all Graph Hero Products content: application/json: schema: type: array items: type: string example: - "12345699" - "12345777" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /products/back-offs: get: tags: - Back-Off Products summary: Get All Graph Back-Off Products description: >- Returns an array that contains all Back-Off products from the Graph operationId: getBackOffProducts parameters: - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- An array of Products that are Back-Off Products with Strategic Pricing, Hero and Back-Off properties content: application/json: schema: type: array items: $ref: "#/components/schemas/BackOffToHeroProduct" example: - itemType: ART itemNo: "975312468" itemName: "Product item Name" retailUnits: - es - nl strategicPricingRole: back-off protectsHero: - itemNo: "12345678" retailUnits: - es - nl - itemNo: "12345690" retailUnits: - es - nl protectedBy: [] upsellArguments: [] - itemType: ART itemNo: "66779933" itemName: "Product item Name" retailUnits: - nl strategicPricingRole: back-off protectsHero: - itemNo: "97239833" retailUnits: - nl - itemNo: "97239836" retailUnits: - nl protectedBy: [] upsellArguments: [] "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /products/back-offs/item-numbers: get: tags: - Back-Off Products summary: Get All Back-Off Product `itemNo` description: Returns an array of all Graph Back-Off Product `itemNo` property operationId: getBackOffItemNumbers parameters: - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- An array of string values that are the `itemNo` of all Graph Back-Off Products content: application/json: schema: type: array items: type: string example: - "99887766" - "55668844" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /products: get: tags: - Products summary: Get a list of product item numbers, passed in the query, with their Back-Off/Hero properties description: > This endpoint takes a comma (,) separated list of product item numbers that are passed in the query as input and returns the same list of item numbers with Back-Off/Hero properties as `result`. If the item is neither a backoff or a hero the `result` will be an empty object operationId: getBackOffToHeroByProductIds parameters: - in: query name: itemNumbers description: A comma (`,`) separated list of product item numbers schema: type: array items: pattern: '^\d+$' minLength: 8 maxLength: 8 type: string example: "12345678" minItems: 1 maxItems: 100 uniqueItems: true style: form explode: false required: true - in: query name: retailUnits description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter. schema: type: array items: type: string uniqueItems: true style: form explode: false required: false - in: query name: enableMarketSalesDate description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date. schema: type: boolean example: true required: false responses: "200": description: >- Returns a list of product item numbers with back-off/hero properties as `result`, or empty `result` if any of the products is neither a Back-Off nor a Hero product content: application/json: schema: type: array items: $ref: "#/components/schemas/BackOffToHeroProductByItemNo" examples: Mix of Back-Off and Hero Products: value: - itemNo: "12345678" result: itemType: ART itemNo: "12345678" itemName: "Product item Name" retailUnits: - se - es strategicPricingRole: back-off protectsHero: - itemNo: "12345699" retailUnits: - se - es - itemNo: "12345777" retailUnits: - se - es protectedBy: [] upsellArguments: [] - itemNo: "98762345" result: itemType: ART itemNo: "98762345" itemName: "Product item Name" retailUnits: - es strategicPricingRole: hero protectsHero: [] protectedBy: - itemNo: "12340217" retailUnits: - es upsellArguments: - shortText: Is more configurable longText: This product comes with more configuration options - shortText: Sustainable longText: This product is made from more sustainable products - shortText: 1 Year Guarentee longText: This product comes with a 1 Year Guarentee Mix of Back-Off product and product which is neither Hero nor Back-Off: value: - itemNo: "12345678" result: itemType: ART itemNo: "12345678" itemName: "Product item Name" retailUnits: - se strategicPricingRole: back-off protectsHero: - itemNo: "12345777" retailUnits: - se protectedBy: [] upsellArguments: [] - itemNo: "98765321" result: {} "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" components: schemas: Product: title: Product type: object nullable: true description: A Product contained with the IKEA Knowledge Graph properties: itemType: description: An IKEA Product type (e.g `ART` or `SPR`) type: string enum: - ART - SPR itemNo: description: The IKEA Product item item number type: string itemName: description: The IKEA Product item name type: string retailUnits: description: A list of retail units. A compilation of retail units is available at https://knowledge.ikea.net/retail-system-module/retail-units-taxonomy type: array items: type: string description: A retail unit identifier UpsellArguments: title: UpsellArguments description: Upsell arguments that are included in a Hero Product properties: shortText: type: string description: A shortened version of the Upsell Argument text longText: type: string description: The full Upsell Argument text required: - shortText - longText BackOffToHeroProduct: title: BackOffToHeroProduct allOf: - $ref: "#/components/schemas/Product" - type: object - description: A facet of an IKEA Product with Hero or Back-Off information properties: strategicPricingRole: description: A text value of the strategic pricing role of the product type: string enum: - back-off - hero protectsHero: description: > If a Back-Off product, an array of string value of the `itemNo` of the Hero products this item protects, otherwise an empty array type: array items: $ref: "#/components/schemas/ProductRetailUnits" protectedBy: description: >- If a Hero Product, the string value of the Back-Off Product itemNo type: array items: $ref: "#/components/schemas/ProductRetailUnits" upsellArguments: description: > If a Hero Product, provide the upsell arguments as strings otherwise an empty array. The items are provided in the array in correct priority order. type: array items: $ref: "#/components/schemas/UpsellArguments" BackOffToHeroProductByItemNo: title: BackOffToHeroProductByItemNo description: Contains a product identifier (itemNo) with corresponding Hero or Back-Off information of the IKEA product properties: itemNo: description: The IKEA Product item number, also known as article number type: string pattern: '^\d+$' minLength: 8 maxLength: 8 result: allOf: - $ref: "#/components/schemas/BackOffToHeroProduct" ProductRetailUnits: title: ProductRetailUnits description: Contains a product identifier (itemNo) with corresponding retail units where the hero or backoff product is available properties: itemNo: description: The IKEA Product item number, also known as article number type: string pattern: '^\d+$' minLength: 8 maxLength: 8 retailUnits: description: The list of common retail units between this product and the product in the inquery. A compilation of retail units is available at https://knowledge.ikea.net/retail-system-module/retail-units-taxonomy type: array items: $ref: "#/components/schemas/RetailUnit" RetailUnit: title: RetailUnit description: A retail unit identifier type: string Error: title: Error description: A generic error response properties: status: type: number type: type: string message: type: string required: - status - type - message responses: BadRequest: description: Bad request content: application/json: schema: $ref: "#/components/schemas/Error" Unauthorized: description: API key is missing or invalid content: application/json: schema: $ref: "#/components/schemas/Error" NotFound: description: Resource not found content: application/json: schema: $ref: "#/components/schemas/Error" InternalServerError: description: A request to the server cannot be processed content: application/json: schema: $ref: "#/components/schemas/Error" securitySchemes: SubscriptionKey: type: apiKey name: Subscription-Key in: header