Aller au contenu
Garanify

Products

Products with brand, model identifier and producer guarantee. Garanify never stores end-customer data.

The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.

List products

GET /v1/shops/{shop}/products

Key: Secret key

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
limit query integer Page size.≥ 1, ≤ 500, default 100
cursor query string Value of nextCursor from the previous page.≤ 400 chars
status query "label" | "none" | "hidden" | "invalid" Only products with this status.

Request

curl "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const page = await garanify.products.list({
  limit: 100
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$page = $garanify->products->list([
    'limit' => 100,
]);
import os, requests

res = requests.get(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()

Response 200 application/json

{
  "data": [
    {
      "sku": "WCR870",
      "parentSku": null,
      "name": "Washing machine W1",
      "brand": "Miele",
      "mpn": "WCR 870 WPS",
      "categories": [
        "Household > Washing machines"
      ],
      "tags": [],
      "garan": {
        "years": 10,
        "brand": null,
        "model": null
      },
      "hidden": false,
      "status": "label",
      "label": {
        "years": 10,
        "brand": "Miele",
        "model": "WCR 870 WPS",
        "source": "product",
        "rule": null
      },
      "errors": [],
      "updatedAt": "2026-11-18T10:00:00Z"
    }
  ],
  "nextCursor": null
}

Responses

  • 200 One page of products, sorted by SKU. · ProductList
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Upsert up to 1000 products

POST /v1/shops/{shop}/products/bulk

Key: Secret key

Creates or replaces up to 1000 products in one atomic request. If one item is invalid against the schema, nothing is written. Send an Idempotency-Key so that a retry after a timeout does not run twice. Pro and Agency.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
Idempotency-Key header string Any unique string (for example a UUID). The same key with the same body returns the stored response for 24 hours.1–255 chars

Body

NameTypeDescription
productsrequired ProductUpsert[] 1–1000 items

Request

curl -X POST "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/bulk" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"products":[{"sku":"WCR870","brand":"Miele","mpn":"WCR 870 WPS","garan":{"years":10}},{"sku":"WAN28200","brand":"Bosch","categories":["Household > Washing machines"]}]}'
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const result = await garanify.products.bulkUpsert([
  {
    sku: 'WCR870',
    brand: 'Miele',
    mpn: 'WCR 870 WPS',
    garan: {
      years: 10
    }
  },
  {
    sku: 'WAN28200',
    brand: 'Bosch',
    categories: [
      'Household > Washing machines'
    ]
  }
]);
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$result = $garanify->products->bulkUpsert([
    [
        'sku' => 'WCR870',
        'brand' => 'Miele',
        'mpn' => 'WCR 870 WPS',
        'garan' => [
            'years' => 10,
        ],
    ],
    [
        'sku' => 'WAN28200',
        'brand' => 'Bosch',
        'categories' => [
            'Household > Washing machines',
        ],
    ],
]);
import os, uuid, requests

res = requests.post(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/bulk",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "products": [
            {
                "sku": "WCR870",
                "brand": "Miele",
                "mpn": "WCR 870 WPS",
                "garan": {
                    "years": 10,
                },
            },
            {
                "sku": "WAN28200",
                "brand": "Bosch",
                "categories": [
                    "Household > Washing machines",
                ],
            },
        ],
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()

Response 200 application/json

{
  "counts": {
    "created": 1,
    "updated": 1,
    "unchanged": 0
  },
  "results": [
    {
      "sku": "WCR870",
      "result": "created",
      "status": "label",
      "label": {
        "years": 10,
        "brand": "Miele",
        "model": "WCR 870 WPS",
        "source": "product",
        "rule": null
      },
      "errors": []
    },
    {
      "sku": "WAN28200",
      "result": "updated",
      "status": "label",
      "label": {
        "years": 5,
        "brand": "Bosch",
        "model": "WAN28200",
        "source": "rule",
        "rule": 1
      },
      "errors": []
    }
  ]
}

Responses

  • 200 Result per product, in request order. · BulkResult
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 403 Plan, key type or origin does not allow the request. · Problem
  • 413 Body larger than allowed. · Problem
  • 422 The request does not match the schema. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Retrieve a product

GET /v1/shops/{shop}/products/{sku}

Key: Secret key

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
skurequired path Sku Your product ID, usually the SKU. URL-encode special characters.1–120 chars, pattern ^[^\x00-\x1f]+$

Request

curl "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const product = await garanify.products.retrieve('WCR870');
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$product = $garanify->products->retrieve('WCR870');
import os, requests

res = requests.get(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()

Responses

  • 200 The product with its resolved label. · Product
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 404 Not found. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Create or replace a product

PUT /v1/shops/{shop}/products/{sku}

Key: Secret key

Stores the product under its SKU (your external ID). The model identifier on the label is garan.model, otherwise the MPN, otherwise the SKU. Never send a GTIN or EAN: it is not a model identifier. Invalid guarantee data (2 years or less, no brand, no model) is stored with status: invalid and shows no label.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
skurequired path Sku Your product ID, usually the SKU. URL-encode special characters.1–120 chars, pattern ^[^\x00-\x1f]+$

Body

NameTypeDescription
parentSku Sku | null SKU of the main product, for variants.
name string | null ≤ 300 chars
brand string | null Brand or manufacturer.≤ 120 chars
mpn string | null Manufacturer part number. Preferred model identifier. Not a GTIN/EAN.≤ 120 chars
categories string[] Category names. A path like Household > Coffee machines also matches its parent categories.0–50 items
tags string[] 0–50 items
garan GaranInput Producer guarantee of the product. Empty values come from the main product or the rules.
garan.years number | null Years, more than 2, whole or half years. 0 or null = not set (main product or rules apply).≥ 0, ≤ 99
garan.brand string | null Brand on the label. Default is brand of the product.≤ 120 chars
garan.model string | null Model identifier on the label. Default is MPN, then SKU.≤ 120 chars
hidden boolean true = never show a GARAN label for this product.

Request

curl -X PUT "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Washing machine W1","brand":"Miele","mpn":"WCR 870 WPS","categories":["Household > Washing machines"],"garan":{"years":10}}'
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const product = await garanify.products.upsert('WCR870', {
  name: 'Washing machine W1',
  brand: 'Miele',
  mpn: 'WCR 870 WPS',
  categories: [
    'Household > Washing machines'
  ],
  garan: {
    years: 10
  }
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$product = $garanify->products->upsert('WCR870', [
    'name' => 'Washing machine W1',
    'brand' => 'Miele',
    'mpn' => 'WCR 870 WPS',
    'categories' => [
        'Household > Washing machines',
    ],
    'garan' => [
        'years' => 10,
    ],
]);
import os, requests

res = requests.put(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    json={
        "name": "Washing machine W1",
        "brand": "Miele",
        "mpn": "WCR 870 WPS",
        "categories": [
            "Household > Washing machines",
        ],
        "garan": {
            "years": 10,
        },
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()

Response 200 application/json

{
  "sku": "WCR870",
  "parentSku": null,
  "name": "Washing machine W1",
  "brand": "Miele",
  "mpn": "WCR 870 WPS",
  "categories": [
    "Household > Washing machines"
  ],
  "tags": [],
  "garan": {
    "years": 10,
    "brand": null,
    "model": null
  },
  "hidden": false,
  "status": "label",
  "label": {
    "years": 10,
    "brand": "Miele",
    "model": "WCR 870 WPS",
    "source": "product",
    "rule": null
  },
  "errors": [],
  "updatedAt": "2026-11-18T10:00:00Z"
}

Responses

  • 200 The stored product with its resolved label. · Product
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 403 Plan, key type or origin does not allow the request. · Problem
  • 422 The request does not match the schema. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Delete a product

DELETE /v1/shops/{shop}/products/{sku}

Key: Secret key

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
skurequired path Sku Your product ID, usually the SKU. URL-encode special characters.1–120 chars, pattern ^[^\x00-\x1f]+$

Request

curl -X DELETE "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
await garanify.products.delete('WCR870');
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$garanify->products->delete('WCR870');
import os, requests

res = requests.delete(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()

Responses

  • 204 Deleted.
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 404 Not found. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Next: Rules