Skip to main content
Catalog

Catalog

Manage your product and service catalog including items, families, subfamilies, and bundles through the BlueRockTEL API.

The catalog covers the product and service catalogue: Items, Families, Subfamilies, and Bundles.

Auth required: Yes (auth:api) for all endpoints.

Model Properties

Item

Property Type Required Description
id integer auto Unique identifier
description string Yes Item name/description
internal_reference string No Internal reference code
bar_code string No EAN/barcode
brand string No Brand name
type string No Item type (enum: item_type)
family_id integer No FK to families. Product family
subfamily_id integer No FK to subfamilies. Product subfamily
tax_id integer No FK to taxes. Applicable VAT rate
supplier_id integer No FK to suppliers. Default supplier
supplier_reference string No Supplier's reference code
buying_price_without_tax decimal No Buying/cost price, excl. tax
selling_price_without_tax decimal No Selling price, excl. tax
monthly_exploitation_fees decimal No Monthly exploitation/maintenance fees
ecotax_amount_included_in_price decimal No Eco-contribution amount included in price
copy_tax_amount_included_in_price decimal No Copy tax amount included in price
selling_service_access_fees_without_tax decimal No Service access fees (selling price), excl. tax
buying_service_access_fees_without_tax decimal No Service access fees (buying price), excl. tax
billing_frequency integer No Default billing frequency in months (default: 1)
active boolean No Whether the item is active (default: true)
active_for_initial_billing boolean No Available for one-time billing (default: false)
active_for_recurring_billing boolean No Available for recurring billing (default: true)
active_for_store boolean No Available in the customer store (default: false)
install boolean No Has an installation fee
install_selling_price_without_tax decimal No Installation selling price, excl. tax
has_consumptions boolean No Whether this item generates consumption billing (default: true)
has_stock boolean No Whether stock tracking is enabled (default: false)
quantity integer No Current stock quantity
alert_stock integer No Stock alert threshold
security_stock integer No Minimum security stock level
replenishment_lead_time string No Lead time for restocking
comment string No Internal notes
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Family

Property Type Required Description
id integer auto Unique identifier
name string Yes Family name
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Subfamily

Property Type Required Description
id integer auto Unique identifier
family_id integer Yes FK to families
name string Yes Subfamily name
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Bundle

A bundle is a pre-packaged set of catalog items that can be added to a customer file in one operation.

Property Type Required Description
id integer auto Unique identifier
name string Yes Bundle name
description string No Bundle description
active boolean No Whether the bundle is available
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Bundle Initial Item (items within the bundle that generate one-time charges):

Property Type Required Description
id integer auto Unique identifier
bundle_id integer Yes FK to bundles
item_id integer Yes FK to items
quantity numeric Yes Item quantity within the bundle
selling_price_without_tax decimal No Override selling price
discount_rate decimal No Discount rate

Items

Base URL: /api/v1/items

Items are the individual products and services sold to customers.

GET /v1/items

List items with filtering, sorting, and pagination. Non-admin/tech users see only active catalog items.

Query parameters:

Parameter Type Description
filter[description] string Filter by description
filter[brand] string Filter by brand
filter[id] integer Filter by exact ID
filter[family_id] integer Filter by family
filter[subfamily_id] integer Filter by subfamily
filter[internal_reference] string Filter by internal reference
filter[active_for_initial_billing] boolean Filter items active for initial billing
sort string Sort field
include string Relations to include
per_page integer Items per page (default 10)

Response 200: Paginated list of item objects with family, subfamily, tax relations and counts.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/items?filter[family_id]=3&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# python requests
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/items",
    params={"filter[family_id]": 3, "per_page": 25},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
items = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/items', [
        'filter[family_id]' => 3,
        'per_page' => 25,
    ]);

$items = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/items?filter[family_id]=3&per_page=25",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
    },
  }
);
const items = await response.json();

POST /v1/items

Create a new catalog item. Requires create permission on Item.

Body (JSON): Validated via Item::attributes('common', 'store').

Response 201: Created item object. Response 403: Insufficient permissions. Response 422/500: Error.

Examples:

# curl
curl -X POST "https://your-instance.bluerocktel.net/api/v1/items" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Fibre 1Gbps",
    "brand": "blue_rock",
    "family_id": 3,
    "subfamily_id": 12,
    "internal_reference": "FIB-1G-001",
    "price": 49.99
  }'

# python requests
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/items",
    json={
        "description": "Fibre 1Gbps",
        "brand": "blue_rock",
        "family_id": 3,
        "subfamily_id": 12,
        "internal_reference": "FIB-1G-001",
        "price": 49.99,
    },
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
item = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/items', [
        'description' => 'Fibre 1Gbps',
        'brand' => 'BlueRock',
        'family_id' => 3,
        'subfamily_id' => 12,
        'internal_reference' => 'FIB-1G-001',
        'price' => 49.99,
    ]);

$item = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/items",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Fibre 1Gbps",
      brand: "blue_rock",
      family_id: 3,
      subfamily_id: 12,
      internal_reference: "FIB-1G-001",
      price: 49.99,
    }),
  }
);
const item = await response.json();

GET /v1/items/{id}

Get a single item with family, subfamily, tax relations.

URL parameters:

Parameter Type Description
id integer Item ID

Response 200: Item object. Response 404: Not found.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/items/42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# python requests
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/items/42",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
item = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/items/42');

$item = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/items/42",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
    },
  }
);
const item = await response.json();

PUT /v1/items/{id}

Update a catalog item.

URL parameters:

Parameter Type Description
id integer Item ID

Body (JSON): Validated via Item::attributes('common').

Response 201: Updated item object. Response 404: Not found.

DELETE /v1/items/{id}

Delete a catalog item. Fails if the item is used in any customer file initials, recurrings, or licences.

Response 200: Success message. Response 404: Not found. Response 422: Item is in use.

GET /v1/items/internal_reference/{internal_reference}

Find an item by its internal reference code.

URL parameters:

Parameter Type Description
internal_reference string Internal reference string

Response 200:

{ "item_id": 42 }

Response 404: Not found.

Families

Base URL: /api/v1/families

Product families are top-level catalog categories.

Standard CRUD (resource routes)

Method Route Description
GET /v1/families List all families
POST /v1/families Create a new family
GET /v1/families/{id} Get a single family
PUT /v1/families/{id} Update a family
DELETE /v1/families/{id} Delete a family

Web only: Ordering families up/down (POST /families/{id}/up, POST /families/{id}/down) is not available in the API.

Examples (GET /v1/families):

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/families" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# python requests
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/families",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
families = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/families');

$families = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/families",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
    },
  }
);
const families = await response.json();

Examples (POST /v1/families):

# curl
curl -X POST "https://your-instance.bluerocktel.net/api/v1/families" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Internet Services"}'

# python requests
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/families",
    json={"name": "Internet Services"},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
family = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/families', [
        'name' => 'Internet Services',
    ]);

$family = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/families",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Internet Services" }),
  }
);
const family = await response.json();

Subfamilies

Base URL: /api/v1/subfamilies

Subfamilies are second-level catalog categories, nested under families.

Standard CRUD (resource routes)

Method Route Description
GET /v1/subfamilies List all subfamilies
POST /v1/subfamilies Create a new subfamily
GET /v1/subfamilies/{id} Get a single subfamily
PUT /v1/subfamilies/{id} Update a subfamily
DELETE /v1/subfamilies/{id} Delete a subfamily

Bundles

Base URL: /api/v1/bundles

Bundles group multiple catalog items into a package.

GET /v1/bundles

List all bundles with item counts (initial, licence, recurring).

Query parameters:

Parameter Type Description
filter[name] string Filter by name
filter[id] integer Filter by exact ID
sort string Sort field
include string Relations (items_initial, items_licence, items_recurring)

Response 200: Array of bundle objects with item counts.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/bundles?include=items_initial,items_recurring" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# python requests
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/bundles",
    params={"include": "items_initial,items_recurring"},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
bundles = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/bundles', [
        'include' => 'items_initial,items_recurring',
    ]);

$bundles = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/bundles?include=items_initial,items_recurring",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
    },
  }
);
const bundles = await response.json();

POST /v1/bundles

Create a new bundle. user_id is auto-set to authenticated user. Requires create permission on Item.

Body (JSON): Validated via Bundle::attributes('common', 'store').

Response 201: Created bundle object.

Examples:

# curl
curl -X POST "https://your-instance.bluerocktel.net/api/v1/bundles" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Starter Pack Fibre"}'

# python requests
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/bundles",
    json={"name": "Starter Pack Fibre"},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
bundle = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/bundles', [
        'name' => 'Starter Pack Fibre',
    ]);

$bundle = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/bundles",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Starter Pack Fibre" }),
  }
);
const bundle = await response.json();

GET /v1/bundles/{id}

Get a single bundle with calculated price sums for each item type (initial, licence, recurring).

URL parameters:

Parameter Type Description
id integer Bundle ID

Response 200: Bundle object with price summaries.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/bundles/7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# python requests
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/bundles/7",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
bundle = response.json()

# php Laravel Http
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/bundles/7');

$bundle = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/bundles/7",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
    },
  }
);
const bundle = await response.json();

PUT /v1/bundles/{id}

Update a bundle.

Response 201: Updated bundle object.

DELETE /v1/bundles/{id}

Delete a bundle.

Response 200: Success message.

Bundle Initial Items

Base URL: /api/v1/bundle-initial-items

Line items within bundles for one-time charges.

Standard CRUD (resource routes)

Method Route Description
GET /v1/bundle-initial-items List all bundle initial items
POST /v1/bundle-initial-items Create a new bundle initial item
GET /v1/bundle-initial-items/{id} Get a single bundle initial item
PUT /v1/bundle-initial-items/{id} Update a bundle initial item
DELETE /v1/bundle-initial-items/{id} Delete a bundle initial item

Suppliers

Base URL: /api/v1/suppliers

GET /v1/suppliers

List all suppliers. Read-only via API.

Response 200: Array of supplier objects.

Next Customer Files