Catalog Ingestion

Catalog Ingestion lets you bring products into Galactic Core from an outside source. When a merchant’s own system — an ERP, a PIM, another storefront, or a spreadsheet export — is the source of truth for the catalog, you push that data to Tybrite instead of entering products by hand. Send a batch as JSON, XML, or CSV; Tybrite matches each row to your existing catalog by SKU, updates what already exists, and creates what doesn’t.

Dashboard: You can register a feed URL for scheduled sync from GC Admin, or push products directly via the API and SDK. Find your signing secret under Integrations → API keys.

Secret key + request signature required. POST /v1/ingest/products is the one write endpoint where both a secret key (tybrite_sk_*) and a signed request are mandatory. A publishable key returns 403; a missing or invalid signature returns 401.

When it applies

Ingestion is the path for a catalog that lives somewhere else and is mirrored into Galactic Core:

A merchant runs their inventory in an ERP/PIM and wants it reflected in their Tybrite store.
You’re migrating a catalog from another platform.
A nightly export from a back-office system should keep the storefront in sync.

Ingestion is a merchant-side write for keeping a catalog up to date, which is why it sits outside the otherwise storefront-facing API and carries stricter authentication than any other write.

Batch size

A request carries at most 12 products. A larger batch is rejected with 400 and nothing is written, rather than applying part of the batch and leaving the rest to fail item by item. For a large catalog, send a sequence of batches, or configure a scheduled sync, which fetches and imports a whole catalog on a timer and has no such limit.

Selling on a marketplace

Nothing changes. A merchant whose store is part of a marketplace pushes their catalog exactly as any other merchant does, with their own store’s secret key, and their products appear on the marketplace storefront alongside everyone else’s once the store is approved. The marketplace listing is a read over the same catalog — approved stores, aggregated — so there is no separate marketplace feed, no marketplace ingestion endpoint, and nothing extra to configure. An operator key is refused with 403 — ingestion is store-scoped, because a catalog belongs to the merchant who owns it rather than to the marketplace that lists it.

Quick start

Ingestion is a write, so initialize the SDK with a secret key and sign each request. Below, one standalone product and one multi-variant product (its rows share a product_group):

import { Tybrite } from '@tybrite-labs/sdk';
import { createHmac } from 'crypto';

const client = new Tybrite({ apiKey: process.env.TYBRITE_SECRET_KEY });

const products = [
  // A standalone, single-variant product
  {
    sku: 'MUG-CERAMIC-WHITE',
    name: 'Ceramic Mug',
    description: 'A 350ml glazed ceramic mug.',
    category: 'Kitchen & Dining',
    price: 12.0,
    stock: 120,
    image: 'https://cdn.yourstore.com/mug-white.jpg',
  },

  // A multi-variant product — three rows sharing one product_group,
  // each with its own unique sku
  {
    sku: 'TEE-CLASSIC-S',
    product_group: 'TEE-CLASSIC',
    name: 'Classic T-Shirt',
    variant_name: 'Small',
    category: 'Men\'s Clothing',
    price: 24.0,
    stock: 40,
  },
  {
    sku: 'TEE-CLASSIC-M',
    product_group: 'TEE-CLASSIC',
    name: 'Classic T-Shirt',
    variant_name: 'Medium',
    category: 'Men\'s Clothing',
    price: 24.0,
    stock: 55,
  },
  {
    sku: 'TEE-CLASSIC-L',
    product_group: 'TEE-CLASSIC',
    name: 'Classic T-Shirt',
    variant_name: 'Large',
    category: 'Men\'s Clothing',
    price: 24.0,
    stock: 30,
  },
];

const result = await client.ingestion.ingestProducts({
  requestBody: { products },
  // strategy: 'create_only',  // optional — skip SKUs that already exist
});

console.log(result.status);   // 'success' | 'partial' | 'failed'
console.log(result.summary);  // { rows_total, rows_created, rows_updated, rows_skipped, rows_failed }
console.log(result.errors);   // [] when everything imported cleanly

The SDK signs the request for you when it’s configured with your secret key. If you call the endpoint directly (curl, another language, a serverless handler), you must add the signing headers yourself — see Signing a request.

How matching by SKU works

Every row carries a sku — your unique stock-keeping unit. That SKU is the identity Galactic Core matches on, scoped to your store:

SKU already exists → the product, its variant, and its stock are updated in place.
SKU is new → a product (and variant) is created.

To import only brand-new products and leave existing ones untouched, pass strategy: 'create_only'. Matching SKUs are then skipped (counted in rows_skipped) rather than updated:

const result = await client.ingestion.ingestProducts({
  requestBody: { products },
  strategy: 'create_only',
});

The default is upsert_by_sku (update existing, create new).

Variants

Rows that share the same non-empty product_group become variants of a single product — each row still needs its own unique sku. A row with no product_group is a standalone, single-variant product. The first row in a group supplies the product-level fields (name, description, category); each row contributes its own variant_name, price, and stock.

Formats

Declare the format with the Content-Type header or the ?format= query parameter. All three normalize to the same result. The SDK sends JSON; the XML and CSV shapes below are for when you push the raw body yourself.

{
  "products": [
    {
      "sku": "MUG-CERAMIC-WHITE",
      "name": "Ceramic Mug",
      "category": "Kitchen & Dining",
      "price": 12.0,
      "stock": 120
    },
    {
      "sku": "TEE-CLASSIC-S",
      "product_group": "TEE-CLASSIC",
      "name": "Classic T-Shirt",
      "variant_name": "Small",
      "category": "Men's Clothing",
      "price": 24.0,
      "stock": 40
    }
  ]
}

<products>
  <product>
    <sku>MUG-CERAMIC-WHITE</sku>
    <name>Ceramic Mug</name>
    <category>Kitchen &amp; Dining</category>
    <price>12.00</price>
    <stock>120</stock>
  </product>
  <product>
    <sku>TEE-CLASSIC-S</sku>
    <product_group>TEE-CLASSIC</product_group>
    <name>Classic T-Shirt</name>
    <variant_name>Small</variant_name>
    <category>Men's Clothing</category>
    <price>24.00</price>
    <stock>40</stock>
  </product>
</products>

sku,product_group,name,variant_name,category,price,stock
MUG-CERAMIC-WHITE,,Ceramic Mug,,Kitchen & Dining,12.00,120
TEE-CLASSIC-S,TEE-CLASSIC,Classic T-Shirt,Small,Men's Clothing,24.00,40

CSV follows standard quoting rules, so commas and newlines inside quoted fields are handled. Field names are matched leniently (e.g. Product Name maps to name).

Product fields

Field	Required	Description
`sku`	Yes	Your unique stock-keeping unit — the identity used for matching.
`name`	Yes	Product name.
`price`	Yes	Selling price. Must be greater than 0.
`product_group`	—	Groups rows into one multi-variant product. Omit for a standalone product.
`variant_name`	—	Label for this variant (e.g. a size or colour). Defaults to `"Default"`.
`description`	—	Product description.
`category`	Yes	The product’s category, by name (or id). Matching is case-insensitive but otherwise exact, against the platform category list. Categories are not created from a feed; a row whose category does not resolve is rejected. An inactive matching category is reactivated automatically.
`subcategory`	—	Subcategory under the category. Unlike categories, subcategories are created automatically if new. Nest with `>`, e.g. `Audio > Headphones > Wireless`.
`brand`	—	Brand name.
`image`	—	Public image URL. A broken URL is a warning, not a failure.
`cost_price`	—	Unit cost.
`stock`	—	On-hand quantity.
`threshold`	—	Low-stock threshold.
`barcode` / `barcode_type`	—	Barcode value and symbology. Common spellings are normalized (e.g. `UPC` → `UPC_A`); unknown values fall back to `CODE128`.

Field names are matched leniently on case, spaces, underscores and hyphens, so Product Name, product_name and productname all reach name. Several fields accept alternative spellings a source system is likely to emit: title for name, qty or quantity for stock, cost for cost_price, handle or parent for product_group, and image_url or image_link for image.

Cost price and margin reporting

cost_price is what margin is calculated from. A product imported without one books no cost against its sales, so its margin reads as the full selling price and every report that rolls margin up reads as complete while resting on that gap. Where the source system holds a unit cost, carrying it in the feed is worth the column; where it does not, the merchant can fill it in afterwards and the figures correct themselves from that point.

Catalog identity and channel fields

A row also carries the identifiers a sales channel matches a listing against and the attributes it lists alongside them. These are read on both the push API and a scheduled sync.

Field	Description
`gtin`	The manufacturer’s global trade item number. Accepted as `gtin`, `ean`, `upc`, `ean13`, `upc_a` or `global_trade_item_number`.
`mpn`	Manufacturer part number. Accepted as `mpn`, `manufacturer_part_number`, `part_number` or `part_no`.
`condition`	One of `new`, `refurbished` or `used`. Common wordings map onto those three — “refurb” and “renewed” read as `refurbished`, “pre-owned” and “open box” as `used` — and anything unrecognized is taken as `new`.
`weight_grams`	Shipping weight in grams, as a whole number. A column named `weight_kg` or `weight_lb` is converted; a column named plainly `weight` is read as grams.
`dimensions_cm`	Free text, e.g. `20x15x5`. Accepted as `dimensions`, `size`, `dims` or `lxwxh`.
`google_product_category` / `meta_product_category`	The channel taxonomy strings, passed through as given.
`tags`	A list of tags. Either a real array or a single string delimited by commas, semicolons or pipes.
`seo_title` / `seo_description` / `seo_keywords`	Storefront metadata. `seo_keywords` is a list on the same terms as `tags`.
`is_online_enabled`	Whether the product is published to the storefront. Reads `true`/`false`, `yes`/`no` and `1`/`0`; an empty value means “not stated” and leaves the current setting alone. A product created by an import starts unpublished whatever this says, and the column applies from the import after that.
`online_price` / `online_sale_price`	Storefront price and sale price, where they differ from the in-store `price`.

gtin and barcode are separate fields. barcode is whatever the merchant scans in-store, which may be an internal label with no meaning outside the store; gtin is the manufacturer’s number a sales channel matches the listing against. A feed carrying only one of them populates both, since in practice that single value serves both purposes.

Your own columns

A column that is not one of the fields above is matched against the custom fields defined on products for your store, by the field’s label — the name shown in the dashboard, which is what you would have called the column.

{
  "sku": "TEE-CLASSIC-M",
  "name": "Classic Tee",
  "category": "Men's Clothing",
  "price": 24.99,
  "Fabric": "Organic cotton",
  "Country of origin": "Portugal"
}

Here Fabric and Country of origin land on the product under fields with those labels. A column matching no defined field is ignored, so extra columns in a source export are safe to leave in. On a scheduled sync, a column matching no field can define one instead of being ignored. The definition takes its label from the column header, so warranty_months reads back as “Warranty Months”, and its type from the value carried — a date, a number, a true/false, or text where none of those fit. A source that keeps a column the store does not model yet therefore carries it across without the merchant having to anticipate it. An auto-defined field is merchant-facing until published. It is visible in the dashboard and in the store’s own exports, and it reaches no storefront and appears in no API response until the merchant publishes it — a feed may model a field, but what a shopper sees stays the merchant’s decision. A single run defines at most 25 fields, so a malformed file, a shifted header row or a wide export cannot fill the field list, and each one records that a feed created it.

Defining a field from a column is a per-source setting on scheduled sync, on by default. With it off, and on the push API, a column is recorded only where a field with that label already exists. Fields are defined in the dashboard under Settings → Custom fields.

Response shape

Rows are validated and applied independently — one bad row never fails the whole batch. The response always carries a summary of counts and an errors array describing every rejected row:

{
  "status": "partial",
  "summary": {
    "rows_total": 15,
    "rows_created": 9,
    "rows_updated": 1,
    "rows_skipped": 1,
    "rows_failed": 4
  },
  "errors": [
    { "row": 3, "sku": "TEE-RED-S", "field": "price", "reason": "price must be a positive number (got 'free')" }
  ]
}

status is success when nothing failed, or partial when some rows failed but others imported. If every row fails validation, the request returns 422 and nothing is written.

Summary fields

Field	Description
`rows_total`	How many rows were in the batch.
`rows_created`	Rows that created a new product or variant.
`rows_updated`	Rows that updated an existing SKU.
`rows_skipped`	Rows skipped — an existing SKU under `create_only`.
`rows_failed`	Rows rejected by validation (see `errors`).

Per-row errors

Each entry in errors pinpoints exactly what to fix:

Field	Description
`row`	The row’s position in the batch.
`sku`	The SKU of the offending row, when available.
`field`	The field that caused the rejection.
`reason`	A human-readable explanation.

Signing a request

The SDK signs for you when initialized with a secret key. If you push the raw body yourself, add three headers. The signature is a base64 HMAC-SHA256 of `${timestamp}.${rawBody}` using your store’s signing secret (the same scheme as orders and payments) — sign the exact bytes you send.

import { createHmac } from 'crypto';

function signIngestRequest(rawBody: string, signingSecret: string) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signature = createHmac('sha256', signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('base64');

  return {
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  };
}

// Raw push (e.g. CSV) without the SDK:
const rawBody = await fs.promises.readFile('catalog.csv', 'utf8');
const headers = {
  'Authorization': `Bearer ${process.env.TYBRITE_SECRET_KEY}`,
  'Content-Type': 'text/csv',
  'Idempotency-Key': crypto.randomUUID(),
  ...signIngestRequest(rawBody, process.env.TYBRITE_SIGNING_SECRET),
};

await fetch('https://api.tybritelabs.com/v1/ingest/products', {
  method: 'POST',
  headers,
  body: rawBody,
});

Header	Required	Purpose
`Idempotency-Key`	Yes	Unique key per batch. Retrying with the same key returns the original result instead of re-processing.
`X-Timestamp`	Yes	Unix time in seconds, within 5 minutes of server time.
`X-Signature`	Yes	Base64 HMAC-SHA256 of `${X-Timestamp}.${raw_body}`.

The signature covers the raw body exactly as sent. Re-serializing the JSON (whitespace or key ordering changes) produces a different byte sequence, and verification fails.

Test without a key

Two public, no-key endpoints validate a feed format ahead of any integration work. Both are rate-limited to 60 requests/hour per IP. A valid sample feed to model your own on (?format=json|xml|csv):

curl "https://api.tybritelabs.com/v1/ingest/sample?format=json"

The sample includes a single-variant product and a multi-variant product, so you can see exactly how product_group expresses variants. A validation run that writes nothing. It returns the same summary and errors a real import would, plus a normalized_preview showing how Galactic Core interpreted each row:

curl -X POST "https://api.tybritelabs.com/v1/ingest/test" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "sku": "MUG-CERAMIC-WHITE", "name": "Ceramic Mug", "price": 12.0, "stock": 120 }
    ]
  }'

From the SDK:

const sample = await client.ingestion.getIngestSample({ format: 'json' });

const check = await client.ingestion.testIngest({
  requestBody: { products },
});

console.log(check.status);              // 'valid' | 'partial' | 'invalid'
console.log(check.normalized_preview);  // how each row was interpreted
console.log(check.errors);              // rows that would be rejected

Scheduled sync

Instead of pushing, you can have Galactic Core pull a feed for you. Register a feed URL in your dashboard, choose a cadence, and Galactic Core fetches and syncs the catalog on that schedule — matching by SKU exactly like the push API.

Which side owns a field

A catalog that syncs on a timer is edited from two directions: the feed carries what moves in the source system, and the merchant curates the listing in their dashboard. Each feed source records who owns each field, which decides what a re-sync does with it. Ownership belongs to the registered source, so it applies to scheduled sync alone. A push carries no source, and the values in the batch are applied as sent. A feed-owned field is rewritten from the feed on every run. A merchant-owned field is written only while its value still matches what the feed last wrote for it; once the merchant changes it, the feed stops touching that field on that product and leaves the edit standing. Other fields on the same product, and the same field on every other product, are unaffected. The defaults put each field with the side that is usually authoritative for it:

Owner by default	Fields
Feed	`price`, `cost_price`, `stock`, `threshold`, `barcode`, `barcode_type`, `gtin`, `mpn`, `condition`, `weight_grams`, `dimensions_cm`, `online_price`, `online_sale_price`
Merchant	`name`, `description`, `category`, `subcategory`, `brand`, `image`, `variant_name`, `seo_title`, `seo_description`, `seo_keywords`, `tags`, `google_product_category`, `meta_product_category`, `is_online_enabled`, and your own columns

Price, cost, stock and the identifiers move in the source system, so the feed keeps them and a scheduled sync goes on correcting them. Names, descriptions, taxonomy, imagery and channel metadata are where a merchant’s own judgement lives, so an edit there survives the next run rather than being reverted by it. The assignment is per source and per field: a merchant who wants the feed to keep restoring product names, or to stop overwriting price, moves that field to the other side in their dashboard.

The first run after a source starts recording ownership has no earlier feed value to compare against, so it writes every field it carries and records them as its baseline. Merchant ownership takes effect from the run after that, which is the first one able to tell an edit from a value nobody has touched.

After each scheduled run, a feed.sync.completed webhook fires with the run’s summary, so your systems can react to the result without polling. Subscribe to it the same way as any other event:

const { webhook_endpoint } = await client.webhooks.createWebhookEndpoint({
  requestBody: {
    url: 'https://yourapp.com/webhooks/tybrite',
    events: ['feed.sync.completed'],
  },
});

See the Webhooks guide for delivery, signing, and idempotency.

Publish your own catalog (outbound feed)

Ingestion works both ways: a store can also expose its own catalog as a public feed for other systems to pull from — another store’s scheduled sync, a partner, a marketplace, or your own tooling. It is enabled in the dashboard under Integrations → Catalog sync → Publish my catalog, which produces a public URL in two formats, readable with no API key:

https://api.tybritelabs.com/v1/feeds/{store}/products.json
https://api.tybritelabs.com/v1/feeds/{store}/products.xml

{store} is your store id or short store code.

On a store belonging to an operated platform, the host is that platform’s own. The dashboard shows the URL to copy, and where the store belongs to an agency it reads https://api.theirplatform.com/v1/feeds/… rather than the address above — a feed URL is pasted into Google Merchant Center or a partner’s system, where it outlives the screen it came from. The path, the formats and the token all behave identically. See Running your own platform.

The feed contains only storefront-safe fields (never cost or margins) and includes each product’s rich media gallery and its published specifications:

{
  "products": [
    {
      "sku": "EARBUDS-01",
      "name": "Wireless Earbuds",
      "category": "Audio & Headphones",
      "subcategory": "Wireless",
      "brand": "Pulsewave",
      "image": "https://cdn.example.com/earbuds.jpg",
      "media": [
        { "url": "https://cdn.example.com/earbuds.jpg", "type": "image", "position": 0, "is_primary": true }
      ],
      "price": 82.0,
      "stock": 60,
      "specifications": {
        "connectivity": "Bluetooth 5.3",
        "battery_life": "24 hours",
        "noise_cancelling": "Active"
      }
    }
  ]
}

The feed shape matches what the ingestion endpoints accept, so a store-to-store sync needs no field mapping: one store’s scheduled sync can point straight at another store’s products.json. A token added in the dashboard and appended as ?token=… keeps a feed semi-private.

Response codes

Code	Meaning
`200`	Batch processed — may be a full or partial success. Inspect `summary` and `errors`.
`400`	Unparseable body, unknown format, or no rows.
`401`	Missing/invalid secret key, or a missing/invalid request signature.
`403`	A publishable key was used — ingestion requires a secret key. An operator key is refused here too: ingestion is store-scoped.
`409`	`Idempotency-Key` reused with a different request body.
`422`	Every row failed validation; nothing was written.
`429`	Rate limit exceeded.
`500`	Internal server error.

SDK reference

See the IngestionService SDK reference for full method signatures, or the API Reference for the raw endpoints.

Introduction

How GC Works

Build with AI

Extend the platform

Commerce capabilities

Distribute

Native Integrations

Resources

When it applies

Batch size

Selling on a marketplace

Quick start

How matching by SKU works

Variants

Formats

Product fields

Cost price and margin reporting

Catalog identity and channel fields

Your own columns

Response shape

Summary fields

Per-row errors

Signing a request

Test without a key

Scheduled sync

Which side owns a field

Publish your own catalog (outbound feed)

Response codes

SDK reference

​When it applies

​Batch size

​Selling on a marketplace

​Quick start

​How matching by SKU works

​Variants

​Formats

​Product fields

​Cost price and margin reporting

​Catalog identity and channel fields

​Your own columns

​Response shape

​Summary fields

​Per-row errors

​Signing a request

​Test without a key

​Scheduled sync

​Which side owns a field

​Publish your own catalog (outbound feed)

​Response codes

​SDK reference

When it applies

Batch size

Selling on a marketplace

Quick start

How matching by SKU works

Variants

Formats

Product fields

Cost price and margin reporting

Catalog identity and channel fields

Your own columns

Response shape

Summary fields

Per-row errors

Signing a request

Test without a key

Scheduled sync

Which side owns a field

Publish your own catalog (outbound feed)

Response codes

SDK reference