Ingestion

The IngestionService class (accessed via client.ingestion) pushes or syncs an external product catalog into your store. When the merchant’s own system — an ERP, a PIM, another storefront, or a spreadsheet export — is the source of truth for products, you send batches here as JSON, XML, or CSV instead of entering products by hand. For the full conceptual guide (matching rules, formats, scheduled sync), see Catalog Ingestion.

Overview

Galactic Core matches each incoming row to your existing catalog by SKU: an existing SKU is updated in place, a new SKU is created. Rows that share a product_group become variants of one product. Every batch returns a summary of counts and a per-row errors array, so one bad row never fails the whole import.

Secret key + request signature required. ingestProducts is a write — initialize the SDK with a secret key (tybrite_sk_*). A publishable key returns 403. The SDK signs the request for you; if you call the endpoint directly, you must add the signing headers yourself (see Signing a request).

`ingestProducts`

Push or sync a batch of products into your store. Parameters:

Parameter	Type	Required	Description
`requestBody.products`	`IngestProduct[]`	Yes	The batch of products. Each row needs a unique `sku`.
`format`	`'json' \| 'xml' \| 'csv'`	—	Overrides format detection. The SDK sends JSON, so you rarely set this.
`strategy`	`'upsert_by_sku' \| 'create_only'`	—	`upsert_by_sku` (default) updates existing SKUs; `create_only` skips them.
`dryRun`	`boolean`	—	When `true`, validate and report without writing anything.

Product fields (each entry in products):

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.
`category`	Yes	The product’s category, matched to an existing category by name (or id). Categories are not created from a feed — a row whose category doesn’t exist is rejected (an inactive one is reactivated automatically).
`product_group`	—	Groups rows into one multi-variant product. Omit (or `null`) for a standalone product.
`variant_name`	—	Label for this variant (e.g. a size or colour). Defaults to `"Default"`.
`description`	—	Product description.
`subcategory`	—	Optional subcategory under the category. Unlike categories, subcategories are created automatically if missing. Use `>` to nest, e.g. `Audio > Headphones > Wireless`.
`brand`	—	Brand name.
`image`	—	Public image URL.
`cost_price`	—	Unit cost.
`stock`	—	On-hand quantity.
`threshold`	—	Low-stock threshold.
`barcode` / `barcode_type`	—	The value scanned in-store and its symbology. A row carrying only `gtin`, `ean` or `upc` populates the barcode from it.

Field names are matched leniently on case, spaces, underscores and hyphens, and several accept alternative spellings: 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. A row also carries catalog identifiers, shipping dimensions, channel taxonomy and storefront metadata: gtin, mpn, condition, weight_grams, dimensions_cm, google_product_category, meta_product_category, tags, seo_title, seo_description, seo_keywords, is_online_enabled, online_price and online_sale_price. See Catalog identity and channel fields. A column matching none of the fields above is matched against the store’s custom fields by label, and recorded on the product where one matches; a column matching none is ignored. cost_price is what margin is calculated from, so a product imported without it books no cost against its sales. A feed registered for scheduled sync decides per field whether the feed or the merchant owns it on a re-sync, so a merchant’s edit can stand rather than being rewritten. That is a property of the registered source: a push applies the values in the batch as sent. See Which side owns a field. Signed example — one standalone product and one multi-variant product (its rows share a product_group):

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

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

const result = await client.ingestion.ingestProducts({
  requestBody: {
    products: [
      // Standalone single-variant product
      {
        sku: 'MUG-CERAMIC-WHITE',
        name: 'Ceramic Mug',
        category: 'Kitchenware',
        price: 12.0,
        stock: 120,
      },
      // Multi-variant product — rows share product_group, each has its own sku
      {
        sku: 'TEE-CLASSIC-S',
        product_group: 'TEE-CLASSIC',
        name: 'Classic T-Shirt',
        variant_name: 'Small',
        category: 'Apparel',
        price: 24.0,
        stock: 40,
      },
      {
        sku: 'TEE-CLASSIC-M',
        product_group: 'TEE-CLASSIC',
        name: 'Classic T-Shirt',
        variant_name: 'Medium',
        category: 'Apparel',
        price: 24.0,
        stock: 55,
      },
    ],
  },
  // 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

Response

{
  "status": "success",
  "dry_run": false,
  "format": "json",
  "strategy": "upsert_by_sku",
  "summary": {
    "rows_total": 2,
    "rows_created": 2,
    "rows_updated": 0,
    "rows_skipped": 0,
    "rows_failed": 0
  },
  "errors": []
}

The SDK signs the request when initialized with your secret key. To push a raw body yourself (curl, another language, a serverless handler), add the X-Timestamp, X-Signature, and Idempotency-Key headers — see Signing a request.

Response fields:

Field	Description
`status`	`success` (no failures), `partial` (some rows failed, the rest applied), or `failed` (every row failed; nothing written).
`format`	The format Galactic Core detected (`json` / `xml` / `csv`).
`strategy`	The strategy applied (`upsert_by_sku` / `create_only`).
`summary`	Per-batch counts (see below).
`errors`	One entry per rejected row (see below).

summary counts:

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`).

errors entries:

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.

`getIngestSample`

Returns a valid sample product feed you can copy to model your own. No API key required. The sample includes a single-variant product and a multi-variant product so you can see exactly how product_group expresses variants. Rate-limited to 60 requests/hour per IP. Parameters:

Parameter	Type	Required	Description
`format`	`'json' \| 'xml' \| 'csv'`	—	The format to return the sample in. Defaults to `json`.

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

console.log(sample.products); // model rows you can adapt to your own catalog

Response

{
  "products": [
    {
      "sku": "SAMPLE-LAMP-01",
      "name": "Aurora LED Desk Lamp",
      "description": "Dimmable desk lamp with USB-C.",
      "category": "Home",
      "brand": "Lumio",
      "price": 36.9,
      "cost_price": 17.2,
      "stock": 40,
      "threshold": 5,
      "barcode": "0850000100017",
      "barcode_type": "EAN13"
    },
    {
      "sku": "SAMPLE-TEE-BLK-S",
      "product_group": "SAMPLE-TEE",
      "name": "Classic Cotton Tee",
      "variant_name": "Black / S",
      "category": "Apparel",
      "brand": "Northwind",
      "price": 22,
      "cost_price": 8.4,
      "stock": 30,
      "threshold": 5
    }
  ]
}

`testIngest`

Parses and validates a feed without writing anything to your store, returning the same summary and errors a real import would — plus a normalized_preview showing how Galactic Core interpreted each row. No API key required, so you can perfect your feed format before integrating. Rate-limited to 60 requests/hour per IP. Parameters:

Parameter	Type	Required	Description
`requestBody.products`	`IngestProduct[]`	Yes	The batch of products to validate (same shape as `ingestProducts`).

const check = await client.ingestion.testIngest({
  requestBody: {
    products: [
      { sku: 'MUG-CERAMIC-WHITE', name: 'Ceramic Mug', category: 'Kitchenware', price: 12.0, stock: 120 },
    ],
  },
});

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

Response

{
  "status": "valid",
  "format": "json",
  "validate_only": true,
  "summary": {
    "rows_total": 1,
    "rows_created": 1,
    "rows_updated": 0,
    "rows_skipped": 0,
    "rows_failed": 0
  },
  "errors": [],
  "normalized_preview": [
    {
      "sku": "MUG-CERAMIC-WHITE",
      "product_group": null,
      "name": "Ceramic Mug",
      "description": null,
      "category": "Kitchenware",
      "subcategory": null,
      "brand": null,
      "image": null,
      "variant_name": null,
      "price": 12,
      "cost_price": null,
      "stock": 120,
      "threshold": null,
      "barcode": null,
      "barcode_type": null,
      "tracking_mode": null
    }
  ]
}

Response fields:

Field	Description
`status`	`valid` (no failures), `partial` (some rows failed), or `invalid` (every row failed).
`format`	The format Galactic Core detected.
`validate_only`	Always `true` — confirms nothing was written.
`summary`	The same per-batch counts as a real import.
`errors`	Rows that would be rejected, with row / SKU / field / reason.
`normalized_preview`	How each row was interpreted after normalization.

Publishing a catalog

Ingestion brings products in. The opposite direction — a store’s catalog published as a public JSON or XML feed that another store can pull and ingest with no field mapping — is read with client.feeds, alongside the store’s llms.txt files and its agent.json.

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.
`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.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Overview

`ingestProducts`

`getIngestSample`

`testIngest`

Publishing a catalog

Response Codes

​Overview

​ingestProducts

​getIngestSample

​testIngest

​Publishing a catalog

​Response Codes

Overview

`ingestProducts`

`getIngestSample`

`testIngest`

Publishing a catalog

Response Codes