Aleta B2B API Documentation

Authentication options for protected endpoints:

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

All responses are JSON. Money values are returned as strings.

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
  • limit — Items per page (default 50, max 250)
  • sku — Filter by partial SKU
  • vendor — Filter by vendor/brand
  • status — active|draft|archived (default active)
  • updated_since — ISO8601 datetime filter

Example call:

curl -X GET "/api/v1/products?sku=E22%20MW43BZGURW-M&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": "-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": "E22 MW43BZGURW-M",
                    "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": "",
                    "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_airone",
        "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)

Example call:

curl -X GET "/api/v1/products/E22%20MW43BZGURW-M?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": "E22 MW43BZGURW-M",
                "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": "",
                "weight": 0,
                "weight_unit": "",
                "inventory_item_id": "gid:\/\/shopify\/InventoryItem\/45338570096862"
            }
        ]
    },
    "meta": {
        "client_id": "client_airone",
        "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

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)

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)

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"
    }
}