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	Enabled when creating or editing the API key

All fitment mutations and queries are served at https://api.withremark.com/graphql and authenticate via the X-Vendor-Api-Key header.

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.withremark.com/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. 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 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.

Create a Target

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

curl -X POST https://api.withremark.com/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 } }",
    "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. 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"}`)

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.

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

curl -X POST https://api.withremark.com/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($input: FitmentTargetsFilterInput) {
  fitmentTargets(input: $input) {
    targets {
      id
      externalId
      label
      facetValues
    }
    nextCursor
  }
}

Supports cursor-based pagination and filtering by facet values:

Input Field	Type	Description
`limit`	Int	Results per page (1–500, default 100)
`cursor`	ID	Cursor for the next page (from the previous response’s `nextCursor`)
`facetValues`	JSON	Filter by exact facet values (e.g., `{"year": "2024", "make": "Honda"}`)

Update a Target

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

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: All variants inherit compatibility with the listed targets.
Variant-level: Specific variants are compatible with specific targets (e.g., a left-side brake pad only fits certain bikes).

External IDs that don’t match existing fitment targets are skipped with a warning — they won’t cause the import to fail. Create your fitment targets before importing products.

AI Assistant Behavior

Once fitment facets and targets are configured, Remark’s AI assistant automatically gains the ability to help customers find compatible products.

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 automatically filter to parts compatible with the customer’s vehicle. 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.

Test

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

Need Help?

Contact support@withremark.com for assistance with fitment setup.

Getting Started

Guides

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

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?

Getting Started

Guides

API

Integrations

Documentation Index

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

​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

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?