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`	—	Barcode value and symbology.

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 your own catalog (the inverse of ingestion)

Ingestion pulls products in. The two feed methods below expose your catalog out as a stable, public URL — so another store, a partner, or a script can pull it the same way ingestion accepts it (a store-to-store sync is a direct pull-and-ingest, no field mapping). Opt in from the admin under Catalog Sync → “Publish my catalog”, optionally protecting it with a token. Only storefront-safe fields are exposed — never cost or margin.

No API key required for either feed method — they read a public, opt-in feed. If the store set a private token, pass it as token.

`getStoreCatalogFeedJson`

Returns a store’s published catalog as JSON. Parameters:

Parameter	Type	Required	Description
`store`	`string`	Yes	The store’s id or its short store code.
`token`	`string`	—	Required only if the store protected its feed with a token.

const feed = await client.ingestion.getStoreCatalogFeedJson({
  store: 'ef7b07d3-424b-4b03-b1d4-30a2d2073b61',
});

console.log(feed.products.length);
// feed.products[0] => {
//   sku: '4K Action Camera SKU…', name: '4K Action Camera',
//   category: 'Cameras & Photography', subcategory: null,  // nullable
//   brand: 'Pulsewave', price: 149, sale_price: 129, stock: 148,
//   media: [], seo_title: '…', seo_keywords: ['4k action camera', …]
// }

FeedProduct fields (superset of the ingestion input shape, plus media + published specifications):

Field	Description
`sku`, `name`, `description`, `category`	Core product fields.
`subcategory`	Subcategory name, or `null` when the product has none.
`brand`	Brand, or `null`.
`image`	A single primary image URL (convenience for simple consumers).
`media`	The full product-level media gallery.
`variant_name`	Variant label, or `null`.
`product_group`	Present on multi-variant products so a consumer can regroup variants; `null` otherwise.
`price`	Selling price.
`sale_price`	Sale price, or `null` when not on sale.
`stock`	On-hand quantity.
`seo_title`, `seo_description`, `seo_keywords`	SEO fields, when present (omitted/`null` to keep the feed lean).
`specifications`	Published specifications as a flat key/value object, when present.

Cost, margin, and any other internal fields are never included in the public feed.

`getStoreCatalogFeedXml`

The XML form of the same public feed. Same opt-in and token rules; returns the catalog as an XML string.

const xml = await client.ingestion.getStoreCatalogFeedXml({
  store: 'ef7b07d3-424b-4b03-b1d4-30a2d2073b61',
});
// xml is a string you can serve or re-parse.

Feed response codes: 200 (the catalog), 404 (no public feed — not opted in, or a wrong/missing token), 429 (rate limit exceeded).

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

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Overview

`ingestProducts`

`getIngestSample`

`testIngest`

Publishing your own catalog (the inverse of ingestion)

`getStoreCatalogFeedJson`

`getStoreCatalogFeedXml`

Response Codes

​Overview

​ingestProducts

​getIngestSample

​testIngest

​Publishing your own catalog (the inverse of ingestion)

​getStoreCatalogFeedJson

​getStoreCatalogFeedXml

​Response Codes

Overview

`ingestProducts`

`getIngestSample`

`testIngest`

Publishing your own catalog (the inverse of ingestion)

`getStoreCatalogFeedJson`

`getStoreCatalogFeedXml`

Response Codes