Getting Started

The SnowBee Public API allows you to integrate your e-commerce platform with SnowBee's inventory and order management system. This guide will help you get started with authentication and making your first API calls.

Prerequisites

Before you begin, you'll need:

• A Client ID and Client Secret provided by SnowBee
• Your Tenant ID (your organization's unique identifier)
• An eCom Store ID or Loyalty Program ID depending on which scope you need

Authentication

The SnowBee API uses OAuth 2.0 with the client credentials flow. To authenticate, make a POST request to the token endpoint:

POST https://api.snowbee.no/v1/tenants/TENANT_ID/oauth2/v2.0/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials",
  "scope": "ecom",
  "resource": "your-ecom-store-id"
}

Request Parameters

Response

{
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The access_token is a JWT that expires in 1 hour (3600 seconds). Include it in the Authorization header for all subsequent API calls:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Base URL

All API requests should be made to:

https://api.snowbee.no/v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/

Replace TENANT_ID and ECOM_STORE_ID with your actual values.

Rate Limiting

The API enforces rate limiting to ensure fair usage:

• 2 requests per second per authenticated client
• Burst allowance of up to 10 requests

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your client.

API Endpoints Overview

Product Catalog

Product Schema (Reference Data)

Orders

Customers

Click & Collect

Example: Create an Order

curl -X POST "https://api.snowbee.no/v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "019c1234-5678-7abc-8def-123456789012",
    "deliveryAddress": {
      "name": "John Doe",
      "street": "Main Street 1",
      "postCode": "0123",
      "city": "Oslo",
      "countryIsoCode": "NO",
      "email": "john@example.com",
      "phone": "+4712345678"
    },
    "invoiceAddress": {
      "street": "Main Street 1",
      "postCode": "0123",
      "city": "Oslo",
      "countryIsoCode": "NO",
      "email": "john@example.com"
    },
    "lineItems": [
      {
        "skuId": "019c1234-5678-7abc-8def-123456789013",
        "quantity": 2,
        "netUnitPrice": 199.00,
        "vatRate": 25.00
      }
    ]
  }'

Line Item SKU Identification

You can identify SKUs in line items using either skuId or skuNumber:

// Using SKU ID (UUID)
{ "skuId": "019c1234-5678-7abc-8def-123456789013", "quantity": 2, ... }

// Using SKU number (your product code)
{ "skuNumber": "PROD-BLK-M", "quantity": 2, ... }

At least one of skuId or skuNumber must be provided for each line item.

Order Constraints

• Order must contain at least one line item
• Each line item must have either skuId or skuNumber
• All SKUs must be in the eCom store's assortment
• customerId is optional - if omitted, the store's default customer is used
• Delivery date is calculated as: order date + store's standard lead time
• Prices are in the company's default currency

Example: Click & Collect Reservation

curl -X POST "https://api.snowbee.no/v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/click_and_collect" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retailStoreId": "019c1234-5678-7abc-8def-123456789012",
    "reservationName": "John Doe",
    "customerId": null,
    "lineItems": [
      {
        "skuId": "019c1234-5678-7abc-8def-123456789013",
        "quantity": 1
      }
    ]
  }'

Response:

{
  "parkedCartId": "019c1234-5678-7abc-8def-123456789014",
  "cartId": "019c1234-5678-7abc-8def-123456789015",
  "reservationName": "John Doe",
  "retailStoreId": "019c1234-5678-7abc-8def-123456789012",
  "retailStoreName": "Oslo Store",
  "lineItems": [
    {
      "cartLineId": "019c1234-5678-7abc-8def-123456789016",
      "skuId": "019c1234-5678-7abc-8def-123456789013",
      "skuNumber": "SKU-001",
      "productName": "Blue T-Shirt",
      "quantity": 1,
      "reservedFromWarehouse": "Oslo Store Warehouse"
    }
  ],
  "createdAt": "2025-01-20T10:30:00.000Z"
}

Click & Collect Constraints

• Retail store must be in the eCom store's click & collect network
• Validates inventory availability before creating reservation
• Returns 400 if insufficient inventory

Example: Get Campaigns

curl -X GET "https://api.snowbee.no/v1/tenants/TENANT_ID/ecom_stores/ECOM_STORE_ID/campaigns" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "campaigns": [
    {
      "id": "019c1234-5678-7abc-8def-123456789012",
      "code": "SUMMER24",
      "name": "Summer Sale 2024",
      "validFrom": "2024-06-01",
      "validTo": "2024-08-31",
      "currencyIsoCode": "NOK",
      "status": "ACTIVE",
      "skus": [
        {
          "skuId": "019c1234-5678-7abc-8def-123456789013",
          "campaignPrice": 299.00
        }
      ]
    }
  ]
}

Campaign statuses:

• PLANNED - Campaign is scheduled but not yet active
• ACTIVE - Campaign is currently running

Error Handling

The API returns standard HTTP status codes:

Error responses include a JSON body with details:

{
  "error": "INVALID_REQUEST",
  "message": "Order must contain at least one line item"
}

Common Error Codes

Important Notes

• All IDs are UUIDv7 format
• Timestamps are ISO 8601 format in UTC
• Phone numbers should be in E.164 format (e.g., +4712345678)
• List endpoints return all items (no pagination)
• Only products/SKUs in your eCom store's assortment are accessible

Next Steps

• API Reference - Full OpenAPI/Swagger documentation
• Events - Azure Service Bus event notifications for real-time updates