Fitment

Fitment lets you define compatibility targets (e.g., vehicles) and associate them with products. When configured, Remark’s AI assistant can help customers narrow down to their specific vehicle and automatically filter search results to compatible parts.

Facets

Define the dimensions of fitment for your catalog (e.g., Year, Make, Model).

Targets

Create specific fitment targets representing individual configurations.

Product Linking

Associate fitment targets with products during import.

AI Assistant

How Remark’s assistant uses fitment data to help customers.

Before You Begin

All fitment operations require an integration API key with the FITMENT_MANAGE permission.

Requirement	Where to find it
Integration API Key	Dashboard → Settings → API Keys
`FITMENT_MANAGE` permission	Select Fitment management under Permissions when you create the key. Permissions can’t be changed later, so create a new key to add one

All fitment mutations and queries are served at https://api.remark.ai/graphql and authenticate via the X-Vendor-Api-Key header. You can also send the key as Authorization: Bearer rmrk_.... Dashboard user tokens aren’t accepted for these operations.

Facets define the dimensions used to describe a fitment target. For vehicles, typical facets are Year, Make, and Model — but you can define whatever dimensions fit your catalog. Facets are ordered by position. This ordering determines the cascading selection flow in the AI assistant (e.g., Year first, then Make, then Model).

mutation CreateFitmentFacet($input: CreateFitmentFacetInput!) {
  createFitmentFacet(input: $input) {
    id
    name
    slug
    position
  }
}

curl -X POST https://api.remark.ai/graphql \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: rmrk_your_api_key" \
  -d '{
    "query": "mutation CreateFitmentFacet($input: CreateFitmentFacetInput!) { createFitmentFacet(input: $input) { id name slug position } }",
    "variables": {
      "input": { "name": "Year", "slug": "year", "position": 0 }
    }
  }'

Field	Type	Required	Description
`name`	String	Yes	Display name (max 255 chars)
`slug`	String	Yes	URL-safe identifier, unique per vendor (max 255 chars). Lowercase alphanumeric with hyphens (e.g., `year`, `make`, `sub-model`)
`position`	Int	Yes	Ordering position (0-indexed). Controls the cascading selection order

query FitmentFacets {
  fitmentFacets {
    id
    name
    slug
    position
  }
}

Returns all facets for the authenticated vendor, ordered by position.

mutation UpdateFitmentFacet($id: ID!, $input: UpdateFitmentFacetInput!) {
  updateFitmentFacet(id: $id, input: $input) {
    id
    name
    position
  }
}

All input fields (name, slug, position) are optional — only include what you want to change.

mutation DeleteFitmentFacet($id: ID!) {
  deleteFitmentFacet(id: $id)
}

Deleting a facet cascades — all associated facet values on targets are removed.

Targets

A fitment target represents a specific configuration (e.g., “2024 Honda CRF450R”). Each target has an externalId you control and a set of facet values keyed by facet slug. Inputs take facetValues as a JSON object keyed by facet slug. Responses return facetValues as a list of { slug, name, value, position }, ordered by facet position.

Create a Target

mutation CreateFitmentTarget($input: CreateFitmentTargetInput!) {
  createFitmentTarget(input: $input) {
    id
    externalId
    label
    facetValues { slug name value position }
  }
}

curl -X POST https://api.remark.ai/graphql \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: rmrk_your_api_key" \
  -d '{
    "query": "mutation CreateFitmentTarget($input: CreateFitmentTargetInput!) { createFitmentTarget(input: $input) { id externalId label facetValues { slug name value position } } }",
    "variables": {
      "input": {
        "externalId": "2024-honda-crf450r",
        "facetValues": { "year": "2024", "make": "Honda", "model": "CRF450R" }
      }
    }
  }'

Field	Type	Required	Description
`externalId`	String	Yes	Your unique identifier for this target (max 255 chars)
`label`	String	No	Display label (max 1,000 chars). Auto-generated from facet values if omitted (e.g., “2024 Honda CRF450R”)
`facetValues`	JSON	Yes	Object keyed by facet slug (e.g., `{"year": "2024", "make": "Honda"}`). Every key must be an existing facet slug. Values max 255 chars

Partial Targets

A target can leave out facets that don’t affect fit. For example, a part that fits every model of a 2024 Honda can use {"year": "2024", "make": "Honda"}. When a customer’s selections match several targets, the assistant uses the one that defines the most facets. A partial target is ignored when another target has the same values plus at least one more facet.

Bulk Upsert Targets

For loading large sets of targets (up to 5,000 per request), use bulkUpsertFitmentTargets. Targets are matched by externalId — existing targets are updated, new ones are created. Each entry replaces the matching target’s facet values. Omitting label regenerates it from the facet values, replacing any label set earlier. A request with duplicate externalId values is rejected.

mutation BulkUpsertFitmentTargets($input: BulkUpsertFitmentTargetsInput!) {
  bulkUpsertFitmentTargets(input: $input) {
    created
    updated
    total
  }
}

curl -X POST https://api.remark.ai/graphql \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: rmrk_your_api_key" \
  -d '{
    "query": "mutation BulkUpsertFitmentTargets($input: BulkUpsertFitmentTargetsInput!) { bulkUpsertFitmentTargets(input: $input) { created updated total } }",
    "variables": {
      "input": {
        "targets": [
          { "externalId": "2024-honda-crf450r", "facetValues": { "year": "2024", "make": "Honda", "model": "CRF450R" } },
          { "externalId": "2024-honda-crf450rx", "facetValues": { "year": "2024", "make": "Honda", "model": "CRF450RX" } },
          { "externalId": "2023-yamaha-yz250f", "facetValues": { "year": "2023", "make": "Yamaha", "model": "YZ250F" } }
        ]
      }
    }
  }'

Response:

{
  "data": {
    "bulkUpsertFitmentTargets": { "created": 3, "updated": 0, "total": 3 }
  }
}

List Targets

query FitmentTargets($first: Int, $cursor: ID, $filter: FitmentTargetsFilterInput) {
  fitmentTargets(first: $first, cursor: $cursor, filter: $filter) {
    nodes {
      id
      externalId
      label
      facetValues { slug name value position }
    }
    totalCount
    hasNextPage
    endCursor
  }
}

Supports cursor-based pagination and filtering by facet values:

Argument	Type	Description
`first`	Int	Results per page (1–100). Required
`cursor`	ID	Cursor for the next page (from the previous response’s `endCursor`)
`filter`	FitmentTargetsFilterInput	`{ "facetValues": { ... } }`. Matches targets with exactly these values for every listed facet slug (e.g., `{"year": "2024", "make": "Honda"}`)

Update a Target

mutation UpdateFitmentTarget($id: ID!, $input: UpdateFitmentTargetInput!) {
  updateFitmentTarget(id: $id, input: $input) {
    id
    label
    facetValues { slug name value position }
  }
}

All input fields (externalId, label, facetValues) are optional. Passing facetValues replaces the target’s full set of facet values.

Omit label to leave it unchanged (it auto-regenerates if facetValues is updated).
Pass label: null to clear it.
Pass label: "..." to override with a specific value.

Delete a Target

mutation DeleteFitmentTarget($id: ID!) {
  deleteFitmentTarget(id: $id)
}

Deleting a target removes all product and variant associations.

Linking Products

Associate fitment targets with products by including fitmentTargetExternalIds in your product import payload. This works with both SFTP and direct API imports.

{
  "externalId": "brake-pad-001",
  "name": "Performance Brake Pads",
  "brandName": "StopTech",
  "externalUrl": "https://store.example.com/products/brake-pad-001",
  "fitmentTargetExternalIds": [
    "2024-honda-crf450r",
    "2023-honda-crf450r"
  ],
  "variants": [
    {
      "externalId": "bp-001-organic",
      "name": "Organic Compound",
      "sku": "ST-BP-ORG-001",
      "fitmentTargetExternalIds": ["2024-honda-crf450r"],
      "prices": [{ "price": 49.99, "currency": "USD" }]
    }
  ]
}

Fitment can be set at the product level, variant level, or both:

Product-level: Variants without their own list inherit the product’s targets.
Variant-level: A variant with its own list fits only those targets, whatever the product-level list says. In the example above, bp-001-organic fits only 2024-honda-crf450r.

Each list replaces the existing associations. Pass [] to clear them, or omit the field to leave them unchanged.

External IDs that don’t match existing fitment targets are ignored without an error. They won’t cause the import to fail. Create your fitment targets before importing products.

AI Assistant Behavior

Once you create at least one fitment facet, the Find fitment action becomes available in the dashboard. Add it to the Actions section of each intent where the assistant should identify the customer’s vehicle.

How it works

Freeform matching: The assistant passes whatever the customer has shared (“my 24 Chevy Silverado 1500”) to the fitment tool in a single call. The tool resolves each freeform value to the catalog’s canonical value, handling aliases and formatting differences.
Targeted disambiguation: If a value is ambiguous or missing, the tool returns the relevant facet and a short list of candidates for the assistant to clarify with the customer — one round-trip at a time.
Target resolution: Once all facets match, the tool returns the resolved fitment target, which is remembered for the rest of the conversation.
Filtered search: Product searches return only compatible products, and only the variants of each product that fit. The assistant mentions the active vehicle filter in results.

Example conversation

Customer: I need brake pads for my 2024 Honda CRF450R Assistant: Got it — I’ll filter results for your 2024 Honda CRF450R. Here are the brake pads that fit your bike: …

Disambiguation only happens when needed:

Customer: brake pads for a 2024 Honda Assistant: Which model? Common options: CRF450R, CRF450RX, CRF250R. Customer: CRF450R Assistant: Filtering for your 2024 Honda CRF450R: …

Setup Checklist

Create facets

Define your fitment dimensions (e.g., Year, Make, Model) with the correct ordering.

Load targets

Bulk upsert your fitment targets with facet values. For large catalogs, batch into requests of up to 5,000 targets each.

Link products

Include fitmentTargetExternalIds in your product import payloads.

Add the action to an intent

Add Find fitment to the intents that handle parts and compatibility questions.

Test

Start a conversation with Remark’s AI assistant and verify the vehicle resolution and filtered search results.

Need Help?

Contact support@remark.ai for assistance with fitment setup.

Getting Started

Guides

Dashboard

API

Integrations

Facets

Targets

Product Linking

AI Assistant

Before You Begin

Facets

Create a Facet

List Facets

Update a Facet

Delete a Facet

Targets

Create a Target

Partial Targets

Bulk Upsert Targets

List Targets

Update a Target

Delete a Target

Linking Products

AI Assistant Behavior

How it works

Example conversation

Setup Checklist

Need Help?

Facets

Targets

Product Linking

AI Assistant

​Before You Begin

​Facets

​Create a Facet

​List Facets

​Update a Facet

​Delete a Facet

​Targets

​Create a Target

​Partial Targets

​Bulk Upsert Targets

​List Targets

​Update a Target

​Delete a Target

​Linking Products

​AI Assistant Behavior

​How it works

​Example conversation

​Setup Checklist

​Need Help?

Before You Begin

Facets

Create a Facet

List Facets

Update a Facet

Delete a Facet

Targets

Create a Target

Partial Targets

Bulk Upsert Targets

List Targets

Update a Target

Delete a Target

Linking Products

AI Assistant Behavior

How it works

Example conversation

Setup Checklist

Need Help?