Skip to content

Connect your own software with the API ​

With the API, your developers connect any system the marketplace has no app for: you push your products, prices, stock and tracking, and the marketplace sends you each order on a webhook.

Connect ​

  1. In Settings > Integrations, pick API: your API key is shown there
  2. Send your marketplace the URL of the webhook that will receive your orders: you get back the webhook secret that signs them

Every request is a POST to one address, with your key and a topic:

POST https://webhooks.garnetmarketplace.com/sellers/api
Authorization: Bearer your_api_key
X-Garnet-Topic: products/update
Content-Type: application/json

Each request is checked and answered 202 Accepted, then applied within seconds. A refused one answers 400 with the list of what is wrong: { "error": ["variants[0].price must be a number"] }.

Products: products/update ​

Creates the product, or updates the one you sent before with the same externalId:

json
{
  "externalId": "tallow-soap-1",
  "title": "Tallow Soap",
  "descriptionHtml": "<p>Handmade tallow soap.</p>",
  "productType": "Soap",
  "tags": ["handmade"],
  "variants": [{ "sku": "SOAP-1", "price": 12, "inventoryQuantity": 20, "weight": { "value": 120, "unit": "GRAMS" } }],
  "images": [{ "src": "https://example.com/soap.jpg", "alt": "Tallow soap" }]
}

Each variant needs a sku and a price; it can also have compareAtPrice, barcode, tracked (stock tracked, default true) and requiresShipping (default true). The weight's unit is GRAMS, KILOGRAMS, OUNCES or POUNDS. For sizes or colours, list them in "productOptions": [{ "name": "Size", "values": ["S", "M"] }] and give each variant its "optionValues": [{ "optionName": "Size", "name": "S" }].

A product you already added in the app is picked up by its SKU at its first push: the push then updates it, its title, description and images included, instead of creating a second one.

Prices and stock: inventory/update ​

Up to 250 variants by SKU: [{ "sku": "SOAP-1", "price": 12, "stock": 18 }]. A SKU the marketplace does not have is skipped.

Orders: your webhook ​

Each order holding your products is sent to your webhook as a POST with X-Garnet-Topic: orders/create, in Shopify's order format, with your items only. Answer with a 2xx. Check it comes from the marketplace: the HMAC-SHA256 of the raw body, keyed with your webhook secret and base64-encoded, must equal the X-Garnet-Hmac-Sha256 header.

Tracking: fulfillments/create ​

When you ship, send the order's id from the webhook: { "orderId": 5538456789012, "trackingNumber": "1Z999AA10123456784", "trackingCompany": "UPS", "trackingUrl": "https://…" }. The order is fulfilled and the customer notified.

Test ​

There is no sandbox: ask your marketplace for a test order, with a 100% discount for instance. It reaches your webhook like any other, and your tracking fulfils it.

If it does not work ​

  • 401: the key is wrong, or sent without Bearer.
  • 202 but nothing changes: the product's externalId or the SKU does not match what you sent before.
  • 202 but the product never appears: a new product with no stock is not imported, unless your marketplace imports out-of-stock products. Send inventoryQuantity on each variant (or tracked: false) and push the product again.
  • No order arrives: the webhook URL is not registered yet, is wrong or not public, or the order holds none of your products.

Ask your marketplace ​

Whether it imports all your products or picks them, and to register or change your webhook URL.