RecommendRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/aftership/main/json-schema/aftership-recommend-request-schema.json",
  "title": "RecommendRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aftership-discoveries-api-openapi.yml#/components/schemas/Recommend_request",
  "x-stoplight": {
    "id": "65lf99vvyab9h"
  },
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "$ref": "#/$defs/Recommend_type",
      "x-stoplight": {
        "id": "q17knw21q1vnt"
      }
    },
    "session_id": {
      "type": "string",
      "x-stoplight": {
        "id": "1tauiauuzijju"
      },
      "description": "Session unique identifier. It is recommended to use this [package](https://www.npmjs.com/package/uuid) to generate UUID."
    },
    "include_filters": {
      "type": "array",
      "x-stoplight": {
        "id": "imh868o3anvim"
      },
      "description": "Include products that correspond to the specified attribute. For the supported filter key, please refer to the [filter key](../../docs/enum/filter_key.md), and for the format of the filter, please refer to the following examples:\n- Conjunctive filtering: [\"tags:Sale\", \"categories:Furniture\"] means tags contain any of ('Sale') and categories contain any of ('Furniture')\n- Disjunctive filtering: [\"tags:Sofa,Couch,Bed\"] means tags contain any of ('Sofa', 'Couch', 'Bed')",
      "items": {
        "x-stoplight": {
          "id": "dg810n9d1rntl"
        },
        "type": "string"
      }
    },
    "exclude_filters": {
      "type": "array",
      "x-stoplight": {
        "id": "95pfws20jfob0"
      },
      "description": "Exclude products that correspond to the specified attribute. For the supported filter key, please refer to the [filter key](../../docs/enum/filter_key.md), and for the format of the filter, please refer to the following examples:\n- Conjunctive filtering: [\"!tags:Sale\", \"!categories:Furniture\"] means tags not contain any of ('Sale') and categories not contain any of ('Furniture')\n- Disjunctive filtering: [\"!tags:Sofa,Couch,Bed\"] means tags not contain any of ('Sofa', 'Couch', 'Bed')",
      "items": {
        "x-stoplight": {
          "id": "dlsczajr3929r"
        },
        "type": "string"
      }
    },
    "limit": {
      "type": "number",
      "x-stoplight": {
        "id": "pz6betphrp9rh"
      },
      "description": "The number of products each page contains.",
      "default": 10,
      "maximum": 100
    },
    "products": {
      "type": "array",
      "x-stoplight": {
        "id": "86vh5e4mogrgv"
      },
      "description": "This parameter is required for `BOUGHT_TOGETHER`, `COMPLEMENTS`, and `SIMILAR` types. For the meaning of products in different scenarios, please refer to [scenarios](../../docs/scenarios/recommendations/best_sellers.md).",
      "items": {
        "$ref": "#/$defs/Partial_product",
        "x-stoplight": {
          "id": "d9z7q7pp2cpg9"
        }
      }
    }
  },
  "$defs": {
    "Partial_product": {
      "x-stoplight": {
        "id": "d9z7q7pp2cpg9"
      },
      "title": "PartialProduct",
      "type": "object",
      "description": "Partial Commerce Product object.",
      "required": [
        "source_id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "x-stoplight": {
            "id": "qvoh36lrc02n8"
          },
          "description": "Unique identifier generated by AfterShip."
        },
        "source_id": {
          "type": "string",
          "x-stoplight": {
            "id": "69wi7113ojvbf"
          },
          "description": "A unique identifier for the product."
        },
        "variants": {
          "type": "array",
          "x-stoplight": {
            "id": "tzqnhrcqfvuu1"
          },
          "description": "Variants of a product.",
          "items": {
            "x-stoplight": {
              "id": "mzzgj6ecdofbg"
            },
            "type": "object",
            "required": [
              "source_id"
            ],
            "properties": {
              "source_id": {
                "type": "string",
                "x-stoplight": {
                  "id": "ezium75ikx5tb"
                },
                "description": "A unique identifier for the product variant."
              }
            }
          }
        }
      }
    },
    "Recommend_type": {
      "x-stoplight": {
        "id": "q17knw21q1vnt"
      },
      "title": "RecommendType",
      "enum": [
        "BEST_SELLERS",
        "BOUGHT_TOGETHER",
        "RANDOM",
        "NEW_ARRIVAL",
        "COMPLEMENTS",
        "SIMILAR"
      ],
      "description": "Default algorithm configuration type."
    }
  }
}