Aleta B2B API Documentation

Authentication options for protected endpoints:

Authorization: Bearer b2b_...
or query string: ?api_key=b2b_...

Responses are JSON by default. Money values are returned as strings.

Add format=csv to download the same data as a UTF-8 CSV file (Excel-compatible, with a header row). CSV exports ignore pagination and return every row that matches the other filters.

GET /api/v1/health

Description: Service health status and version information.

Auth: Optional

Example call:

curl -X GET "/api/v1/health"

{
    "status": "<string>",
    "version": "<string>",
    "shopify_api_version": "<string>",
    "timestamp": "<string>",
    "client_id": "<null>"
}

{
    "status": "ok",
    "version": "1.0.0",
    "shopify_api_version": "2026-01",
    "timestamp": "2026-03-13T14:00:00Z",
    "client_id": null
}

GET /api/v1/products

Description: List products with B2B pricing and image fields.

Auth: Required (Bearer or api_key query)

Query parameters:

cursor — Pagination cursor (JSON only)
limit — Items per page (default 50, max 250, JSON only)
sku — Filter by partial SKU
vendor — Filter by vendor/brand
status — active|draft|archived (default active)
updated_since — ISO8601 datetime filter
format — csv downloads every matching variant as products.csv. cursor and limit are ignored.

CSV download: One row per variant. Pagination is ignored, so the file contains every product that matches the other filters.

File: products.csv

CSV columns:

product_id, title, handle, vendor, product_type, status, updated_at, featured_image_url, featured_image_alt, image_urls, variant_id, sku, variant_title, retail_price, client_price, public_price, direct_delivery_price, discount_percent, direct_delivery_margin_percent, compare_at_price, barcode, weight, weight_unit, inventory_item_id, variant_image_url

curl -L -X GET "/api/v1/products?status=active&format=csv&api_key=b2b_your_key_here" -o products.csv

Example call:

curl -X GET "/api/v1/products?sku=3700123456780&status=active&limit=50&api_key=b2b_your_key_here"

{
    "data": [
        {
            "id": "<string>",
            "title": "<string>",
            "handle": "<string>",
            "vendor": "<string>",
            "product_type": "<string>",
            "status": "<string>",
            "updated_at": "<string>",
            "featured_image": {
                "url": "<string>",
                "alt": "<string>"
            },
            "images": [
                {
                    "url": "<string>",
                    "alt": "<string>"
                }
            ],
            "variants": [
                {
                    "id": "<string>",
                    "sku": "<string>",
                    "title": "<string>",
                    "retail_price": "<string>",
                    "client_price": "<string>",
                    "public_price": "<string>",
                    "direct_delivery_price": "<string>",
                    "discount_percent": "<int>",
                    "direct_delivery_margin_percent": "<int>",
                    "compare_at_price": "<string>",
                    "image_url": "<string>",
                    "barcode": "<string>",
                    "weight": "<int>",
                    "weight_unit": "<string>",
                    "inventory_item_id": "<string>"
                }
            ]
        }
    ],
    "pagination": {
        "has_next_page": "<bool>",
        "cursor": "<string>",
        "total_fetched": "<int>"
    },
    "meta": {
        "client_id": "<string>",
        "generated_at": "<string>",
        "cached": "<bool>",
        "cache_age_seconds": "<int>"
    }
}

{
    "data": [
        {
            "id": "gid:\/\/shopify\/Product\/7754974068958",
            "title": "GURU WIND - Fullsuit 4\/3 BZ Summer 2022 OYSTERPRENE",
            "handle": "guru-wind-fullsuit-4-3-bz-oysterprene",
            "vendor": "sooruz",
            "product_type": "WETSUIT MEN",
            "status": "active",
            "updated_at": "2026-03-03T23:22:16Z",
            "featured_image": {
                "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
                "alt": ""
            },
            "images": [
                {
                    "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
                    "alt": ""
                }
            ],
            "variants": [
                {
                    "id": "gid:\/\/shopify\/ProductVariant\/43243434868958",
                    "sku": "3700123456780",
                    "title": "M",
                    "retail_price": "99.50",
                    "client_price": "99.50",
                    "public_price": "199.00",
                    "direct_delivery_price": "139.30",
                    "discount_percent": 0,
                    "direct_delivery_margin_percent": 30,
                    "compare_at_price": "194.50",
                    "image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-FT2.jpg?v=1659960983",
                    "barcode": "3700123456780",
                    "weight": 0,
                    "weight_unit": "",
                    "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/45338570096862"
                }
            ]
        }
    ],
    "pagination": {
        "has_next_page": false,
        "cursor": "eyJsYXN0X2lkIjo...",
        "total_fetched": 1
    },
    "meta": {
        "client_id": "client_aleta_surf_shop",
        "generated_at": "2026-03-26T16:27:26+00:00",
        "cached": false,
        "cache_age_seconds": 0
    }
}

GET /api/v1/products/{sku}

Description: Get a single SKU with parent product info, prices, and images.

Auth: Required (Bearer or api_key query)

Query parameters:

format — csv downloads that SKU as products.csv.

CSV download: One row for the requested SKU.

File: products.csv

CSV columns:

curl -L -X GET "/api/v1/products/3700123456780?format=csv&api_key=b2b_your_key_here" -o products.csv

Example call:

curl -X GET "/api/v1/products/3700123456780?api_key=b2b_your_key_here"

{
    "data": {
        "id": "<string>",
        "title": "<string>",
        "handle": "<string>",
        "vendor": "<string>",
        "product_type": "<string>",
        "status": "<string>",
        "updated_at": "<string>",
        "featured_image": {
            "url": "<string>",
            "alt": "<string>"
        },
        "images": [
            {
                "url": "<string>",
                "alt": "<string>"
            }
        ],
        "variants": [
            {
                "id": "<string>",
                "sku": "<string>",
                "title": "<string>",
                "retail_price": "<string>",
                "client_price": "<string>",
                "public_price": "<string>",
                "direct_delivery_price": "<string>",
                "discount_percent": "<int>",
                "direct_delivery_margin_percent": "<int>",
                "compare_at_price": "<string>",
                "image_url": "<string>",
                "barcode": "<string>",
                "weight": "<int>",
                "weight_unit": "<string>",
                "inventory_item_id": "<string>"
            }
        ]
    },
    "meta": {
        "client_id": "<string>",
        "generated_at": "<string>",
        "cached": "<bool>",
        "cache_age_seconds": "<int>"
    }
}

{
    "data": {
        "id": "gid:\/\/shopify\/Product\/7754974068958",
        "title": "-50% \/ GURU WIND - Fullsuit 4\/3 BZ Summer 2022 OYSTERPRENE",
        "handle": "guru-wind-fullsuit-4-3-bz-oysterprene",
        "vendor": "sooruz",
        "product_type": "WETSUIT MEN",
        "status": "active",
        "updated_at": "2026-03-03T23:22:16Z",
        "featured_image": {
            "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
            "alt": ""
        },
        "images": [
            {
                "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
                "alt": ""
            }
        ],
        "variants": [
            {
                "id": "gid:\/\/shopify\/ProductVariant\/43243434868958",
                "sku": "3700123456780",
                "title": "M",
                "retail_price": "99.50",
                "client_price": "99.50",
                "public_price": "199.00",
                "direct_delivery_price": "139.30",
                "discount_percent": 0,
                "direct_delivery_margin_percent": 30,
                "compare_at_price": "194.50",
                "image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-FT2.jpg?v=1659960983",
                "barcode": "3700123456780",
                "weight": 0,
                "weight_unit": "",
                "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/45338570096862"
            }
        ]
    },
    "meta": {
        "client_id": "client_aleta_surf_shop",
        "generated_at": "2026-03-26T16:27:26+00:00",
        "cached": false,
        "cache_age_seconds": 0
    }
}

GET /api/v1/stock

Description: Get stock levels across locations.

Auth: Required (Bearer or api_key query)

Query parameters:

sku — Comma-separated SKUs
location_id — Filter by location id
low_stock — Only rows where available <= value
format — csv downloads every matching stock row as stock.csv.

CSV download: One row per SKU and location.

File: stock.csv

CSV columns:

sku, inventory_item_id, location_id, location_name, available, on_hand, committed, incoming

curl -L -X GET "/api/v1/stock?sku=REF-001-BLK,REF-002-RED&format=csv&api_key=b2b_your_key_here" -o stock.csv

Example call:

curl -X GET "/api/v1/stock?sku=REF-001-BLK,REF-002-RED&api_key=b2b_your_key_here"

{
    "data": [
        {
            "sku": "<string>",
            "inventory_item_id": "<string>",
            "locations": [
                {
                    "location_id": "<string>",
                    "location_name": "<string>",
                    "quantities": {
                        "available": "<int>",
                        "on_hand": "<int>",
                        "committed": "<int>",
                        "incoming": "<int>"
                    }
                }
            ]
        }
    ],
    "meta": {
        "generated_at": "<string>",
        "cached": "<bool>",
        "cache_age_seconds": "<int>"
    }
}

{
    "data": [
        {
            "sku": "REF-001-BLK",
            "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/456",
            "locations": [
                {
                    "location_id": "gid:\/\/shopify\/Location\/1",
                    "location_name": "Main Warehouse",
                    "quantities": {
                        "available": 42,
                        "on_hand": 50,
                        "committed": 8,
                        "incoming": 100
                    }
                }
            ]
        }
    ],
    "meta": {
        "generated_at": "2026-03-13T14:00:00Z",
        "cached": true,
        "cache_age_seconds": 15
    }
}

GET /api/v1/stock/{sku}

Description: Get stock for one SKU across all locations.

Auth: Required (Bearer or api_key query)

Query parameters:

format — csv downloads that SKU as stock.csv.

CSV download: One row per location for the requested SKU.

File: stock.csv

CSV columns:

sku, inventory_item_id, location_id, location_name, available, on_hand, committed, incoming

curl -L -X GET "/api/v1/stock/REF-001-BLK?format=csv&api_key=b2b_your_key_here" -o stock.csv

Example call:

curl -X GET "/api/v1/stock/REF-001-BLK?api_key=b2b_your_key_here"

{
    "data": {
        "sku": "<string>",
        "inventory_item_id": "<string>",
        "locations": [
            {
                "location_id": "<string>",
                "location_name": "<string>",
                "quantities": {
                    "available": "<int>",
                    "on_hand": "<int>",
                    "committed": "<int>",
                    "incoming": "<int>"
                }
            }
        ]
    },
    "meta": {
        "generated_at": "<string>",
        "cached": "<bool>",
        "cache_age_seconds": "<int>"
    }
}

{
    "data": {
        "sku": "REF-001-BLK",
        "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/456",
        "locations": [
            {
                "location_id": "gid:\/\/shopify\/Location\/1",
                "location_name": "Main Warehouse",
                "quantities": {
                    "available": 42,
                    "on_hand": 50,
                    "committed": 8,
                    "incoming": 100
                }
            }
        ]
    },
    "meta": {
        "generated_at": "2026-03-13T14:00:00Z",
        "cached": false,
        "cache_age_seconds": 0
    }
}

GET /api/v1/locations

Description: List all active Shopify locations.

Auth: Required (Bearer or api_key query)

Query parameters:

format — csv downloads every location as locations.csv.

CSV download: One row per location.

File: locations.csv

CSV columns:

id, name, is_active

curl -L -X GET "/api/v1/locations?format=csv&api_key=b2b_your_key_here" -o locations.csv

Example call:

curl -X GET "/api/v1/locations?api_key=b2b_your_key_here"

{
    "data": [
        {
            "id": "<string>",
            "name": "<string>",
            "is_active": "<bool>"
        }
    ],
    "meta": {
        "generated_at": "<string>"
    }
}

{
    "data": [
        {
            "id": "gid:\/\/shopify\/Location\/1",
            "name": "Main Warehouse",
            "is_active": true
        }
    ],
    "meta": {
        "generated_at": "2026-03-13T14:00:00Z"
    }
}

GET /api/v1/catalog

Description: List products with B2B pricing and stock levels joined onto each variant.

Auth: Required (Bearer or api_key query)

Query parameters:

cursor — Pagination cursor (JSON only)
limit — Items per page (default 50, max 250, JSON only)
sku — Filter by partial SKU
vendor — Filter by vendor/brand
status — active|draft|archived (default active)
updated_since — ISO8601 datetime filter
location_id — Only variants with stock at this location
low_stock — Only variants with available <= value
format — csv downloads the full filtered catalog as catalog.csv. cursor and limit are ignored.

CSV download: One row per variant and location. A variant with no stock still appears once, with empty stock columns. Pagination is ignored.

File: catalog.csv

CSV columns:

curl -L -X GET "/api/v1/catalog?status=active&format=csv&api_key=b2b_your_key_here" -o catalog.csv

Example call:

curl -X GET "/api/v1/catalog?status=active&limit=50&api_key=b2b_your_key_here"

{
    "data": [
        {
            "id": "<string>",
            "title": "<string>",
            "handle": "<string>",
            "vendor": "<string>",
            "product_type": "<string>",
            "status": "<string>",
            "updated_at": "<string>",
            "featured_image": {
                "url": "<string>",
                "alt": "<string>"
            },
            "images": [
                {
                    "url": "<string>",
                    "alt": "<string>"
                }
            ],
            "variants": [
                {
                    "id": "<string>",
                    "sku": "<string>",
                    "title": "<string>",
                    "retail_price": "<string>",
                    "client_price": "<string>",
                    "public_price": "<string>",
                    "direct_delivery_price": "<string>",
                    "discount_percent": "<int>",
                    "direct_delivery_margin_percent": "<int>",
                    "compare_at_price": "<string>",
                    "image_url": "<string>",
                    "barcode": "<string>",
                    "weight": "<int>",
                    "weight_unit": "<string>",
                    "inventory_item_id": "<string>",
                    "locations": [
                        {
                            "location_id": "<string>",
                            "location_name": "<string>",
                            "quantities": {
                                "available": "<int>",
                                "on_hand": "<int>",
                                "committed": "<int>",
                                "incoming": "<int>"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "has_next_page": "<bool>",
        "cursor": "<null>",
        "total_fetched": "<int>"
    },
    "meta": {
        "client_id": "<string>",
        "generated_at": "<string>",
        "cached": "<bool>",
        "cache_age_seconds": "<int>"
    }
}

{
    "data": [
        {
            "id": "gid:\/\/shopify\/Product\/7754974068958",
            "title": "GURU WIND - Fullsuit 4\/3 BZ Summer 2022 OYSTERPRENE",
            "handle": "guru-wind-fullsuit-4-3-bz-oysterprene",
            "vendor": "sooruz",
            "product_type": "WETSUIT MEN",
            "status": "active",
            "updated_at": "2026-03-03T23:22:16Z",
            "featured_image": {
                "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
                "alt": ""
            },
            "images": [
                {
                    "url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-BK2.jpg?v=1659960983",
                    "alt": ""
                }
            ],
            "variants": [
                {
                    "id": "gid:\/\/shopify\/ProductVariant\/43243434868958",
                    "sku": "3700123456780",
                    "title": "M",
                    "retail_price": "99.50",
                    "client_price": "99.50",
                    "public_price": "199.00",
                    "direct_delivery_price": "139.30",
                    "discount_percent": 0,
                    "direct_delivery_margin_percent": 30,
                    "compare_at_price": "194.50",
                    "image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0644\/4662\/8062\/products\/E22-MW-SOORUZ-COMBINAISON-SURF-GURU-WIND-BZ-BLUE-FT2.jpg?v=1659960983",
                    "barcode": "3700123456780",
                    "weight": 0,
                    "weight_unit": "",
                    "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/45338570096862",
                    "locations": [
                        {
                            "location_id": "gid:\/\/shopify\/Location\/1",
                            "location_name": "Main Warehouse",
                            "quantities": {
                                "available": 42,
                                "on_hand": 50,
                                "committed": 8,
                                "incoming": 100
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "has_next_page": false,
        "cursor": null,
        "total_fetched": 1
    },
    "meta": {
        "client_id": "client_aleta_surf_shop",
        "generated_at": "2026-03-26T16:27:26+00:00",
        "cached": false,
        "cache_age_seconds": 0
    }
}

Aleta B2B API Documentation

Response format

Example response

Response format

Example response

Response format

Example response

Response format

Example response

Response format

Example response

Response format

Example response

Response format

Example response