openapi: 3.2.0 info: title: Mapp Fashion Recommendations API version: '10' description: 'Mapp Fashion (Dressipi) recommendation API. Assembled verbatim from the per-operation OpenAPI fragments Mapp publishes on each endpoint page of https://docs.mapp.com/apidocs/. The base URL is customer-specific: https://your-domain.com/api/{endpoint}.' security: - api_key: [] user_token: [] tags: - name: recommendations description: Operations about recommendations paths: /recommendations/facetted: post: summary: return facetted recommendations for a user description: "The facetted recommendations api allows retrieval of the most recommended garments for a user.\nThe result set can be filtered by specifying one or more filters. Optionally retrieval of information\nabout the number of hits for other values of the filter are returned\n\nThe currently recognized aggregations are\n\n- garment_category\n- brand\n- occasion\n- must_have\n- retailer_labels (previously known as retailer_categories): significance dependent on retailer and data present in feed\n- store: if dressipi has been provided with per-store availability data, this filters or aggregates on availability by store\n- feature_ids (dressipi feature ids)\n- not_features_ids (dressipi feature ids). This returns results without any of the listed feature ids\n- price\n- reduced_by (range filter that accepts values from 0 to 100)\n- season: filters or aggregates on the season a garment belongs to. Allowed season codes are of the form `ss_YYYY` (spring/summer) or `aw_YYYY` (autumn/winter), e.g. `ss_2024`, `aw_2024`\n\nThe retailer_labels aggregation allows you to query against fields in the product feed consumed by dressipi (these should\nbe agreed with dressipi)\n\nFor example to request a garment category of 1 (dresses) submit\n\n```\n{\n \"facets\": [\n {\n \"name\": \"garment_category\",\n \"value\": [1]\n }\n ]\n}\n```\n\nMultiple values can be passed for a single filter, these will be or-ed.\n\nFor example, to select garments that have all of\n\n- feature id 1 or 2,\n- feature id 3 or 4\n\nsubmit\n```\n{\n \"facets\": [\n {\n \"name\": \"feature_ids\",\n \"filters\": [\n {\"value\": [1,2]},\n {\"value\": [3,4]}\n ]\n }\n ]\n}\n```\n\nMultiple filters can be passed, these will be and-ed (Specifying multiple filters with the same name is not supported)\nFor example, to return items matching a specific retailer label and available from a specific store, submit\n\n```\n{\n \"facets\": [\n {\n \"name\": \"retailer_labels\",\n \"value\": [1,2]\n },\n {\n \"name\": \"store\",\n \"value\": [\"storeID1\",\"storeID2\"]\n }\n ]\n}\n```\n\n\nIf the size for a facet is set to non 0, count information will be returned about other filter values. Conceptually, the count returned in an agggregation bucket is the number of results you would get if the query was filtered by that aggregation value.\n\nNumerical facets use a slightly different syntax, for example\n\n```\n{\n \"facets\": [\n {\n \"name\": \"price\",\n \"filters\": [\n {\n \"from\": 50,\n \"to\": 100\n }\n ],\n \"ranges\": [\n {\"to\": 50},\n {\"from\": 50, \"to\": 100},\n {\"from\": 100}\n ]\n }\n ]\n}\n```\nreturns items whose price between 50 (inclusive) and 100 and the number of results within each of the indicated price ranges.\n\n\n```\n{\n \"facets\": [\n {\n \"name\": \"reduced_by\",\n \"filters\": [\n {\n \"from\": 30\n }\n ]\n }\n ]\n}\n```\n\nReturns items reduced by at least 30%\n\n\n```\n{\n \"facets\": [\n {\n \"name\": \"season\",\n \"filters\": [\n {\"value\": [\"ss_2026\"]}\n ]\n }\n ]\n}\n```\n\nReturns items belonging to the Spring/Summer 2026 season\n\n\nDepending on the garment_format requested, extra fields may be present on the garment, however `garment_id` and `raw_garment_id`\nwill always be present\n" parameters: - in: query name: garment_format description: 'The desired response format. The response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response. The `detailed` format includes the most amount of item metadata (name, description, price etc). The `document` format only includes item identifiers, and if requested dressipi generated information about the item, such as predicted size. The `retailer_ids` format only returns the item identifiers. ' required: false schema: type: string enum: - detailed - document - retailer_ids default: retailer_ids - in: query name: fields description: A list of garment attributes to fetch. Only supported for garment_format=document or detailed. Custom fields may be available - contact dressipi for details required: false schema: type: array items: type: string enum: - size - why - verdict - recommendedness - features - occasions - garment_category_id - owned - department - eans - in: query name: pretty description: 'If true, pretty print json output. This increases response size and should usually be off in production environments ' required: false schema: type: boolean - in: query name: include_dressipi_ids description: 'Controls whether dressipi garment ids (raw_garment_id) are included in response ' required: false schema: type: boolean default: true - in: query name: page description: 'The page from which to start results ' required: false schema: type: integer format: int32 default: 1 - in: query name: per_page description: 'The number of result to return per page ' required: false schema: type: integer format: int32 default: 12 - in: query name: device_type description: 'A device type identifier. This allows segmenting a/b test statistics in the same way as you do. ' required: false schema: type: string - in: query name: locale description: 'A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only function if the corresponding information is in the product feed & processed accordingly. If stock local and UI language are not the same, specify the language parameter in addition to this one. ' required: false schema: type: string - in: query name: language description: 'Allows you to specify a locale used for feed attributes such as product name that should be localized using a different locale to price & stock information. This parameter will only function if the corresponding information is in the product feed & processed accordingly. ' required: false schema: type: string responses: '200': description: Information about the recommended garments content: application/json: schema: $ref: '#/components/schemas/FacettedRecommendationsResponse' '422': description: error message content: application/json: schema: $ref: '#/components/schemas/Error' tags: - recommendations operationId: postRecommendationsFacetted requestBody: content: application/json: schema: $ref: '#/components/schemas/postRecommendationsFacetted' required: true /recommendations/themed: get: summary: return themed recommendations for a user description: 'The themed recommendations api allows retrieval of the most recommended garments for a user matching a theme. Themes should be agreed in advance with dressipi. This is the api equivalent of the plp widget. ' parameters: - in: query name: garment_format description: 'The desired response format. The response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response. The `detailed` format includes the most amount of item metadata (name, description, price etc). The `document` format only includes item identifiers, and if requested dressipi generated information about the item, such as predicted size. The `retailer_ids` format only returns the item identifiers. ' required: false schema: type: string enum: - detailed - document - retailer_ids default: retailer_ids - in: query name: pretty description: 'If true, pretty print Json output. This increases response size and should usually be off in production environments ' required: false schema: type: boolean - in: query name: include_dressipi_ids description: 'Controls whether dressipi garment ids (raw_garment_id) are included in response ' required: false schema: type: boolean default: true - in: query name: device_type description: 'A device type identifier. This allows segmenting a/b test statistics in the same way as you do. ' required: false schema: type: string - in: query name: locale description: 'A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only function if the corresponding information is in the product feed & processed accordingly. If stock local and UI language are not the same, specify the language parameter in addition to this one. ' required: false schema: type: string - in: query name: language description: 'Allows you to specify a locale used for feed attributes such as product name that should be localized using a different locale to price & stock information. This parameter will only function if the corresponding information is in the product feed & processed accordingly. ' required: false schema: type: string - in: query name: theme description: The theme identifier, as agreed with Dressipi. required: true schema: type: string - in: query name: count description: The number of recommendations to return required: false schema: type: integer format: int32 default: 6 responses: '200': description: Information about the related garments content: application/json: schema: $ref: '#/components/schemas/ThemedRecommendationsResponse' '422': description: error message content: application/json: schema: $ref: '#/components/schemas/Error' tags: - recommendations operationId: getRecommendationsThemed x-apievangelist-provenance: method: searched generated: '2026-08-12' source: https://docs.mapp.com/apidocs/ (per-endpoint OpenAPI fragments, Mapp Fashion API) note: Union of the Swagger 2.0 fragments Mapp publishes per endpoint. The swagger/schemes envelope is added by API Evangelist; Mapp does not publish securityDefinitions for the api_key/user_token schemes its security block references, so they are recorded in authentication/ rather than invented here.