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
| Name | In | Type | Description |
|---|---|---|---|
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()Try it GET /v1/shops/{shop}/products
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
200One page of products, sorted by SKU. ·ProductList401Key missing, invalid, expired or revoked. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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()Try it POST /v1/shops/{shop}/products/bulk
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
200Result per product, in request order. ·BulkResult401Key missing, invalid, expired or revoked. ·Problem403Plan, key type or origin does not allow the request. ·Problem413Body larger than allowed. ·Problem422The request does not match the schema. ·Problem429Too many requests. Wait `Retry-After` seconds. ·Problem
Retrieve a product
GET /v1/shops/{shop}/products/{sku}
Key: Secret key
Parameters
| Name | In | Type | Description |
|---|---|---|---|
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()Try it GET /v1/shops/{shop}/products/{sku}
Responses
200The product with its resolved label. ·Product401Key missing, invalid, expired or revoked. ·Problem404Not found. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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()Try it PUT /v1/shops/{shop}/products/{sku}
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
200The stored product with its resolved label. ·Product401Key missing, invalid, expired or revoked. ·Problem403Plan, key type or origin does not allow the request. ·Problem422The request does not match the schema. ·Problem429Too many requests. Wait `Retry-After` seconds. ·Problem
Delete a product
DELETE /v1/shops/{shop}/products/{sku}
Key: Secret key
Parameters
| Name | In | Type | Description |
|---|---|---|---|
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()Try it DELETE /v1/shops/{shop}/products/{sku}
Responses
204Deleted.401Key missing, invalid, expired or revoked. ·Problem404Not found. ·Problem429Too many requests. Wait `Retry-After` seconds. ·Problem