Send product data

Products and variants

In Endear, products are the parent catalog item that customers see (e.g. "T-Shirt") and variants are the individual SKUs sold under that product (e.g. "T-Shirt - Black - M"). A product has one or more variants, and every variant references its parent through product_id.

This split lets Endear track pricing and customer behavior at the SKU level while keeping product-level reporting — titles, tags, media, vendor — clean.

When your source isn't modeled this way

Some platforms — particularly those selling single-SKU items like one-of-a-kind goods — don't separate products from variants. In that case, send each item as both a product and a variant: create one bulkUpsertExternalProducts record and one bulkUpsertExternalProductVariants record per item, where the variant is the sole child of its product. Mirroring the identifiers makes the relationship easy to follow (e.g. prod_123 and var_123).

This keeps your data compatible with Endear's schema without forcing you to fabricate variants you don't have.

Both records must exist

Whether you have true variants or a single SKU per product, a variant is only useful in Endear once its parent product also exists, and vice versa. Sync products before variants, and make sure both are included in any backfill — partial data leads to broken reports, lists, and customer-facing displays.

Push product records

Example product records

Let's assume you have products that look something like this:

Example mutation

You can push these records using any HTTP compatible library:

fetch("https://api.endearhq.com", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-endear-api-key": "{{API_KEY}}",
  },
  body: JSON.stringify({
    query: `
      mutation BulkUpsertExternalProducts($products: [ExternalProductInput!]!) {
        bulkUpsertExternalProducts(products: $products) {
            status
        }
      }
    `,
    variables: {
      products: [
        {
          id: "prod_1",
          sku: "TS01942",
          title: "Best T-Shirt Ever",
          vendor: "Acme Co",
          type: ["tops"],
          tags: ["best-seller", "summer"],
          description_html: "<p>Softest t-shirt you've ever worn.</p>",
          url: "http://www.example.com/products/t-shirt-prod_1",
          available_for_sale: true,
          image_id: "1",
          media: [
            {
              id: "1",
              src: "http://www.example.com/products/t-shirt-prod_1.jpg",
              alt: "Best T-Shirt Ever",
            },
          ],
          created_at: "2016-01-01T00:00:00Z",
          updated_at: "2016-01-01T00:00:00Z",
        },
        {
          id: "prod_2",
          sku: "TS01943",
          title: "Second Best T-Shirt",
          vendor: "Acme Co",
          type: ["tops"],
          tags: ["summer"],
          available_for_sale: true,
          created_at: "2016-01-01T00:00:00Z",
          updated_at: "2016-01-01T00:00:00Z",
        },
      ],
    },
  }),
});