Catalog: API Documentation: BSS for MSP, Telecom & Cloud

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

buying_price_without_tax and selling_price_without_tax are the legacy single-currency fields. Multi-currency pricing is managed through the Item Selling Price and Item Supplier Price resources below, and is embedded on this item as selling_prices and supplier_prices.

Item Selling Price

A per-currency selling price for an item. One row per (item_id, currency) pair — POSTing an existing pair updates it instead of erroring.

Property	Type	Required	Description
`id`	integer	auto	Unique identifier
`item_id`	integer	Yes	FK to items
`currency`	string	Yes	Currency code: `EUR`, `USD`, `GBP`, or `CHF`
`selling_price`	decimal	Yes	Selling price in the given currency
`created_at`	datetime	auto	Creation timestamp
`updated_at`	datetime	auto	Last update timestamp

Item Supplier Price

A per-supplier, per-currency buying/cost price for an item. One row per (item_id, supplier_id, currency) triple — POSTing an existing triple updates it instead of erroring. Setting is_default: true automatically unsets is_default on every other supplier price for the same item.

Property	Type	Required	Description
`id`	integer	auto	Unique identifier
`item_id`	integer	Yes	FK to items
`supplier_id`	integer	Yes	FK to suppliers
`currency`	string	Yes	Currency code: `EUR`, `USD`, `GBP`, or `CHF`
`buying_price`	decimal	Yes	Buying/cost price in the given currency
`supplier_ref`	string	No	Supplier's reference code for this price
`is_default`	boolean	No	Whether this is the default supplier price for the item (default: `false`)
`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'). Optionally accepts nested selling_prices and supplier_prices arrays to set multi-currency prices in the same call, as an alternative to the dedicated Item Selling Prices and Item Supplier Prices endpoints below:

{
  "description": "Fibre 1Gbps",
  "selling_prices": [
    { "currency": "EUR", "selling_price": 49.99 }
  ],
  "supplier_prices": [
    { "supplier_id": 7, "currency": "EUR", "buying_price": 29.99, "is_default": true }
  ]
}

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. The response also embeds the item's selling_prices and supplier_prices.

URL parameters:

Parameter	Type	Description
`id`	integer	Item ID

Response 200: Item object, e.g.:

{
  "id": 42,
  "description": "Fibre 1Gbps",
  "selling_price_without_tax": "49.99",
  "selling_prices": [
    { "id": 1, "item_id": 42, "currency": "EUR", "selling_price": "49.99" }
  ],
  "supplier_prices": [
    { "id": 1, "item_id": 42, "supplier_id": 7, "currency": "EUR", "buying_price": "29.99", "supplier_ref": null, "is_default": true }
  ]
}

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'). Accepts the same optional nested selling_prices/supplier_prices arrays as POST /v1/items, above. Rows are upserted by (currency) / (supplier_id, currency) — a currency omitted from the array is left untouched, not deleted. To remove a price, use DELETE on its dedicated endpoint instead.

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.

Item Selling Prices

Base URL: /api/v1/item-selling-prices

Per-currency selling prices for an item. See Item Selling Price above.

GET /v1/item-selling-prices

List item selling prices with filtering, sorting, and pagination.

Query parameters:

Parameter	Type	Description
`filter[item_id]`	integer	Filter by item
`filter[currency]`	string	Filter by currency
`sort`	string	Sort field
`include`	string	Relations to include (`item`)
`per_page`	integer	Items per page (default 10)

Response 200: Paginated list of item selling price objects.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/item-selling-prices?filter[item_id]=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/item-selling-prices",
    params={"filter[item_id]": 42},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
prices = response.json()

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

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/item-selling-prices', [
        'filter[item_id]' => 42,
    ]);

$prices = $response->json();

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

POST /v1/item-selling-prices

Create (or update, if the item_id/currency pair already exists) a selling price for an item.

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

Response 201: Created (or updated) item selling price object. Response 422/500: Error.

Examples:

# curl
curl -X POST "https://your-instance.bluerocktel.net/api/v1/item-selling-prices" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_id": 42, "currency": "EUR", "selling_price": 49.99}'

# python requests
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/item-selling-prices",
    json={"item_id": 42, "currency": "EUR", "selling_price": 49.99},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
price = response.json()

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

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/item-selling-prices', [
        'item_id' => 42,
        'currency' => 'EUR',
        'selling_price' => 49.99,
    ]);

$price = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/item-selling-prices",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ item_id: 42, currency: "EUR", selling_price: 49.99 }),
  }
);
const price = await response.json();

GET /v1/item-selling-prices/{id}

Get a single item selling price.

URL parameters:

Parameter	Type	Description
`id`	integer	Item selling price ID

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

PUT /v1/item-selling-prices/{id}

Update an item selling price.

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

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

DELETE /v1/item-selling-prices/{id}

Delete an item selling price.

Response 200: Success message. Response 404: Not found.

Item Supplier Prices

Base URL: /api/v1/item-supplier-prices

Per-supplier, per-currency buying/cost prices for an item. See Item Supplier Price above.

GET /v1/item-supplier-prices

List item supplier prices with filtering, sorting, and pagination.

Query parameters:

Parameter	Type	Description
`filter[item_id]`	integer	Filter by item
`filter[supplier_id]`	integer	Filter by supplier
`filter[currency]`	string	Filter by currency
`sort`	string	Sort field
`include`	string	Relations to include (`item`, `supplier`)
`per_page`	integer	Items per page (default 10)

Response 200: Paginated list of item supplier price objects.

Examples:

# curl
curl -X GET "https://your-instance.bluerocktel.net/api/v1/item-supplier-prices?filter[item_id]=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/item-supplier-prices",
    params={"filter[item_id]": 42},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
prices = response.json()

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

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/item-supplier-prices', [
        'filter[item_id]' => 42,
    ]);

$prices = $response->json();

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

POST /v1/item-supplier-prices

Create (or update, if the item_id/supplier_id/currency triple already exists) a supplier price for an item. A supplier ID must first be obtained via GET /v1/suppliers — suppliers are read-only via the API. Setting is_default: true automatically unsets is_default on every other supplier price for the same item; only one supplier price per item can be default.

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

Response 201: Created (or updated) item supplier price object. Response 422/500: Error.

Examples:

# curl
curl -X POST "https://your-instance.bluerocktel.net/api/v1/item-supplier-prices" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_id": 42, "supplier_id": 7, "currency": "EUR", "buying_price": 29.99, "is_default": true}'

# python requests
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/item-supplier-prices",
    json={
        "item_id": 42,
        "supplier_id": 7,
        "currency": "EUR",
        "buying_price": 29.99,
        "is_default": True,
    },
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Accept": "application/json",
    },
)
price = response.json()

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

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/item-supplier-prices', [
        'item_id' => 42,
        'supplier_id' => 7,
        'currency' => 'EUR',
        'buying_price' => 29.99,
        'is_default' => true,
    ]);

$price = $response->json();

// javascript fetch
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/item-supplier-prices",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      item_id: 42,
      supplier_id: 7,
      currency: "EUR",
      buying_price: 29.99,
      is_default: true,
    }),
  }
);
const price = await response.json();

GET /v1/item-supplier-prices/{id}

Get a single item supplier price.

URL parameters:

Parameter	Type	Description
`id`	integer	Item supplier price ID

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

PUT /v1/item-supplier-prices/{id}

Update an item supplier price. Setting is_default: true automatically unsets is_default on every other supplier price for the same item.

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

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

DELETE /v1/item-supplier-prices/{id}

Delete an item supplier price.

Response 200: Success message. 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.

Suppliers themselves have no price fields. Buying/cost prices are attached to items via Item Supplier Prices, above.