Size Charts

Size charts let you maintain a reusable bank of sizing guides and tie one to each product. Charts can be supplied as markdown or as a PDF — PDFs are converted to markdown automatically on ingestion. When a product has an associated chart, Remark’s AI assistant can pull it up to answer sizing questions in conversation.

Managing Charts

Create, update, and bulk-load size charts from markdown or PDF.

PDF Ingestion

Supply a PDF by URL or upload; it’s converted to markdown asynchronously.

Product Linking

Associate a size chart with a product during import.

AI Assistant

How Remark’s assistant uses size charts to help customers.

Before You Begin

All size chart operations require an integration API key with the SIZE_CHART_MANAGE permission.

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

All size chart 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. Each size chart has an externalId you control. This is how you reference a chart when associating it with products, and how bulk operations match existing charts.

Managing Charts

A size chart has a name, an externalId, and a markdown body. The body can be supplied directly as markdown, or generated from a PDF (see PDF Ingestion).

Create a Chart

Provide exactly one of body (markdown) or sourceUrl (a PDF URL).

mutation CreateSizeChart($input: CreateSizeChartInput!) {
  createSizeChart(input: $input) {
    id
    externalId
    name
    source
    status
    body
  }
}

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 CreateSizeChart($input: CreateSizeChartInput!) { createSizeChart(input: $input) { id externalId name source status body } }",
    "variables": {
      "input": {
        "externalId": "mens-footwear",
        "name": "Men'\''s Footwear Size Guide",
        "body": "| US | EU | UK |\n|----|----|----|\n| 8 | 41 | 7 |\n| 9 | 42 | 8 |\n| 10 | 43 | 9 |"
      }
    }
  }'

Field	Type	Required	Description
`externalId`	String	Yes	Your unique identifier for this chart (max 255 chars)
`name`	String	Yes	Display name (max 255 chars)
`body`	String	One of	Markdown body (max 50,000 chars). Provide exactly one of `body` or `sourceUrl`
`sourceUrl`	String	One of	Publicly fetchable URL of a PDF to convert to markdown on ingestion (max 2,048 chars). Provide exactly one of `body` or `sourceUrl`

A chart created from markdown is READY immediately. A chart created from a PDF is PENDING until conversion completes — see PDF Ingestion. Each externalId must be unique. To create or update charts by externalId, use Bulk Upsert.

List Charts

query SizeCharts($first: Int, $cursor: ID) {
  sizeCharts(first: $first, cursor: $cursor) {
    nodes {
      id
      externalId
      name
      source
      status
      body
      conversionError
    }
    totalCount
    hasNextPage
    endCursor
  }
}

Returns your size charts with cursor-based pagination. Pass first (1–100) and the previous response’s endCursor to page forward.

Update a Chart

mutation UpdateSizeChart($id: ID!, $input: UpdateSizeChartInput!) {
  updateSizeChart(id: $id, input: $input) {
    id
    name
    status
    body
  }
}

All input fields (externalId, name, body, sourceUrl) are optional — only include what you want to change. Pass at most one of body or sourceUrl. Passing body replaces the content with markdown and sets the chart to READY. Passing sourceUrl clears the body and sets the chart to PENDING until the new PDF converts.

Delete a Chart

mutation DeleteSizeChart($id: ID!) {
  deleteSizeChart(id: $id)
}

Deleting a chart unlinks it from any associated products — those products simply lose their size chart. It does not affect the products otherwise.

Bulk Upsert

For loading large sets of charts (up to 5,000 per request), use bulkUpsertSizeCharts. Charts are matched by externalId — existing charts are updated, new ones are created. A request with duplicate externalId values is rejected.

mutation BulkUpsertSizeCharts($input: BulkUpsertSizeChartsInput!) {
  bulkUpsertSizeCharts(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 BulkUpsertSizeCharts($input: BulkUpsertSizeChartsInput!) { bulkUpsertSizeCharts(input: $input) { created updated total } }",
    "variables": {
      "input": {
        "sizeCharts": [
          { "externalId": "mens-footwear", "name": "Men'\''s Footwear", "body": "| US | EU |\n|----|----|\n| 9 | 42 |" },
          { "externalId": "womens-apparel", "name": "Women'\''s Apparel", "sourceUrl": "https://cdn.example.com/charts/womens-apparel.pdf" }
        ]
      }
    }
  }'

Each entry takes the same body / sourceUrl rules as Create a Chart. Response:

{
  "data": {
    "bulkUpsertSizeCharts": { "created": 1, "updated": 1, "total": 2 }
  }
}

Bulk Delete

Delete up to 5,000 charts by externalId in a single call. Unknown external IDs are skipped and counted in notFound. A request with duplicate externalId values is rejected.

mutation BulkDeleteSizeCharts($input: BulkDeleteSizeChartsInput!) {
  bulkDeleteSizeCharts(input: $input) {
    deleted
    notFound
    total
  }
}

PDF Ingestion

If your sizing guides are PDFs, you can hand Remark a PDF and it will convert it to markdown for you. There are two ways to supply one: By URL — pass sourceUrl to createSizeChart, updateSizeChart, or any bulk upsert entry. Remark fetches and converts the PDF. By upload — for PDFs not hosted at a public URL, upload the file directly with uploadSizeChartPdf:

mutation UploadSizeChartPdf($externalId: String!, $name: String!, $file: Upload!) {
  uploadSizeChartPdf(externalId: $externalId, name: $name, file: $file) {
    id
    externalId
    status
  }
}

The upload creates the chart, or replaces the content of an existing chart with the same externalId. Send it as a GraphQL multipart request with an Apollo-Require-Preflight: true header. The file must be a PDF of at most 50 MB.

curl https://api.remark.ai/graphql \
  -H "X-Vendor-Api-Key: rmrk_your_api_key" \
  -H "Apollo-Require-Preflight: true" \
  -F 'operations={"query":"mutation UploadSizeChartPdf($externalId: String!, $name: String!, $file: Upload!) { uploadSizeChartPdf(externalId: $externalId, name: $name, file: $file) { id externalId status } }","variables":{"externalId":"womens-apparel","name":"Womens Apparel","file":null}}' \
  -F 'map={"0":["variables.file"]}' \
  -F '0=@womens-apparel.pdf;type=application/pdf'

Whether you pass a URL or upload a file, the chart is saved with source: PDF and status: PENDING, and conversion runs in the background.

Conversion Status

Every chart exposes a status reflecting where its body stands:

Status	Meaning
`READY`	The markdown `body` is available for use. Markdown charts are `READY` immediately
`PENDING`	A PDF source is queued, converting, or retrying; `body` is not yet populated
`FAILED`	Conversion failed after 3 attempts. See `conversionError` for the reason

Poll sizeCharts and check each chart’s status to see when a PDF finishes converting. Conversion is typically fast, but you should treat a chart as usable only once it reaches READY.

bulkUpsertSizeCharts doesn’t re-convert a chart whose sourceUrl is unchanged, unless its last conversion failed. If you replace the PDF at the same URL, call updateSizeChart with the sourceUrl, or use a new URL.

Linking Products

Associate a size chart with a product by including sizeChartExternalId in your product import payload. This works with both SFTP and direct API imports. Each product can have one size chart.

{
  "externalId": "trail-runner-shoe",
  "name": "Trail Runner Shoe",
  "brandName": "Summit",
  "externalUrl": "https://store.example.com/products/trail-runner-shoe",
  "sizeChartExternalId": "mens-footwear"
}

The association is tri-state:

Omit sizeChartExternalId to leave the existing association unchanged.
null clears the association.
An external ID sets the association. An unknown external ID clears it.

Create your size charts before importing products. Referencing an external ID that doesn’t match an existing chart clears the product’s association rather than failing the import.

AI Assistant Behavior

Once you’ve created at least one size chart, the Find size chart action becomes available in the dashboard. Add it to the Actions section of each intent that handles sizing or fit questions, so the assistant can look up a product’s chart during those conversations.

How it works

Lookup: When a customer asks about sizing for a product, the assistant looks up that product’s associated chart by ID or name.
In-conversation answer: If the chart is READY, the assistant uses its markdown to answer the customer’s question directly — recommending a size, reading off measurements, or comparing across the table.
PDF fallback: If the chart’s PDF is still converting (PENDING) or conversion failed (FAILED), the assistant falls back to linking the customer to the original PDF so they’re never left without a sizing reference.

Example conversation

Customer: What size should I get in the Trail Runner Shoe? I’m a US 9.5. Assistant: For the Trail Runner Shoe, a US 9.5 maps to a EU 43. These run true to size, so a 9.5 should be a good fit.

Setup Checklist

Load your charts

Create or bulk upsert your size charts from markdown or PDF. For large catalogs, batch into requests of up to 5,000 charts each.

Wait for conversion

For PDF charts, confirm each reaches READY before relying on it.

Link products

Include sizeChartExternalId in your product import payloads.

Add the action to an intent

Add Find size chart to the intents that handle sizing and fit questions.

Test

Start a conversation with Remark’s AI assistant and ask a sizing question about a linked product.

Need Help?

Contact support@remark.ai for assistance with size chart setup.

Getting Started

Guides

Dashboard

API

Integrations

Managing Charts

PDF Ingestion

Product Linking

AI Assistant

Before You Begin

Managing Charts

Create a Chart

List Charts

Update a Chart

Delete a Chart

Bulk Upsert

Bulk Delete

PDF Ingestion

Conversion Status

Linking Products

AI Assistant Behavior

How it works

Example conversation

Setup Checklist

Need Help?

Managing Charts

PDF Ingestion

Product Linking

AI Assistant

​Before You Begin

​Managing Charts

​Create a Chart

​List Charts

​Update a Chart

​Delete a Chart

​Bulk Upsert

​Bulk Delete

​PDF Ingestion

​Conversion Status

​Linking Products

​AI Assistant Behavior

​How it works

​Example conversation

​Setup Checklist

​Need Help?

Before You Begin

Managing Charts

Create a Chart

List Charts

Update a Chart

Delete a Chart

Bulk Upsert

Bulk Delete

PDF Ingestion

Conversion Status

Linking Products

AI Assistant Behavior

How it works

Example conversation

Setup Checklist

Need Help?