API Integration

The API integration allows vendors without a supported e-commerce platform to connect with a Common Goods marketplace via a REST API. Vendors can push products, update prices and stock, submit tracking information, and receive orders via webhook.

Integration scope

• ✅ Product synchronization (push from vendor)
• ✅ Price and stock updates
• ✅ Order synchronization (webhook to vendor)
• ✅ Tracking synchronization (push from vendor)

Authentication

All API requests must include a Bearer token in the Authorization header. The API key is provided when the marketplace admin creates the integration in > Settings > Integrations > API.

Authorization: Bearer your_api_key

Base URL: https://api.garnetmarketplace.com

Quick start

Here is a full example: create a pineapple product, then update its stock.

Step 1 — Create the product:

Response:

{ "productId": "gid://shopify/Product/123456789" }

Step 2 — Update stock and price:

Response:

{ "updated": 1, "unknownSkus": [] }

Endpoints

POST /products

Create or update a product in the marketplace. If a product with the same externalId already exists, it will be updated. On first creation, the product is created as DRAFT. The marketplace admin can then approve and publish it.

Request body:

Product option

Variant

Image

Metafield

Example request:

curl -X POST https://api.garnetmarketplace.com/products \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "vendor-product-123",
    "title": "Premium Leather Bag",
    "descriptionHtml": "<p>A beautiful leather bag</p>",
    "productType": "Bags",
    "tags": ["leather", "premium"],
    "productOptions": [
      { "name": "Size", "values": ["S", "M", "L"] }
    ],
    "variants": [
      {
        "sku": "BAG-001-S",
        "price": 129.99,
        "inventoryQuantity": 50,
        "optionValues": [{ "optionName": "Size", "name": "S" }]
      },
      {
        "sku": "BAG-001-M",
        "price": 129.99,
        "inventoryQuantity": 30,
        "optionValues": [{ "optionName": "Size", "name": "M" }]
      }
    ],
    "images": [
      { "src": "https://example.com/bag-front.jpg", "alt": "Front view" }
    ],
    "metafields": [
      { "key": "material", "value": "leather" },
      { "key": "country_of_origin", "value": "Italy" }
    ]
  }'

Response:

{ "productId": "gid://shopify/Product/123456789" }

PATCH /products

Bulk update price and stock for existing products by SKU. Maximum 250 items per request. Only updates variants that match existing SKUs in the marketplace.

Request body: Array of objects:

Example request:

curl -X PATCH https://api.garnetmarketplace.com/products \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '[
    { "sku": "BAG-001-S", "price": 119.99, "stock": 45 },
    { "sku": "BAG-001-M", "price": 119.99, "stock": 28 }
  ]'

Response:

{ "updated": 1, "unknownSkus": [] }

POST /tracking

Submit a tracking number for an order. This will fulfill the order on the marketplace and notify the customer.

Request body:

Example request:

curl -X POST https://api.garnetmarketplace.com/tracking \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 5538456789012,
    "trackingNumber": "1Z999AA10123456784",
    "trackingCompany": "UPS",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }'

Response:

{ "fulfilled": true }

Webhooks

When a customer places an order on the marketplace, Garnet sends it to the vendor's system as a webhook: an HTTP POST request to the vendor's registered webhook URL, with the order as JSON payload.

Topics

The order only contains the vendor's own line items: an order spanning several vendors is split, and each vendor receives their share only.

Each delivery includes the following headers:

Respond with a 2xx status code to acknowledge the delivery. Any other response is treated as a failed delivery and reported to the Garnet team.

Verifying a webhook

Before processing a delivery, verify it was sent by Garnet and not by a third party. Compute the HMAC-SHA256 digest of the raw request body using your webhook secret as the key, base64-encode it, and compare it to the X-Garnet-Hmac-Sha256 header using a constant-time comparison. If they differ, reject the request with a 401 status.

import crypto from 'crypto';

function verifyWebhook(rawBody, hmacHeader, secret) {
  const digest = crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('base64');
  return crypto.timingSafeEqual(Buffer.from(digest, 'base64'), Buffer.from(hmacHeader, 'base64'));
}

Order payload

The payload follows the Shopify Order datatype — the exact same format Shopify uses for its own orders/create and orders/updated webhooks.

Error responses

All endpoints return JSON errors in the following format:

{ "error": "Error message describing what went wrong" }