Skip to content

Marketplace Component Usages

Operations Summary

Method Endpoint Description
Core CRUD
GET /api/marketplace-component-usages/ List component usage records
GET /api/marketplace-component-usages/{uuid}/ Retrieve a component usage record
Other Actions
POST /api/marketplace-component-usages/set_usage/ Set component usage for a resource
POST /api/marketplace-component-usages/{uuid}/set_user_usage/ Set user-specific component usage

Core CRUD

List component usage records

Returns a paginated list of component usage records for resources. This data is used for billing and usage tracking.

1
2
3
4
http \
  GET \
  https://api.example.com/api/marketplace-component-usages/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.marketplace_component_usages import marketplace_component_usages_list # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = marketplace_component_usages_list.sync(client=client)

for item in response:
    print(item)
  1. API Source: marketplace_component_usages_list
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { marketplaceComponentUsagesList } from 'waldur-js-client';

try {
  const response = await marketplaceComponentUsagesList({
  auth: "Token YOUR_API_TOKEN"
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Description
billing_period string (date)
billing_period_month number Billing period month
billing_period_year number Billing period year
customer_uuid string (uuid) Customer UUID
date_after string (date) Date after or equal to
date_before string (date) Date before or equal to
field array
o array Ordering
offering_uuid string (uuid) Offering UUID
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.
project_uuid string (uuid) Project UUID
resource string Resource URL
resource_uuid string (uuid) Resource UUID
type string Component type

200 -

The response body is an array of objects, where each object has the following structure:

Field Type Description
uuid string (uuid)
created string (date-time)
description string
type string Unique internal name of the measured unit, for example floating_ip.
name string Display name for the measured unit, for example, Floating IP.
measured_unit string Unit of measurement, for example, GB.
usage integer
date string (date-time)
recurring boolean Reported value is reused every month until changed.
resource_name string
resource_uuid string (uuid)
offering_name string
offering_uuid string (uuid)
project_name string
project_uuid string
customer_name string
customer_uuid string
billing_period string (date)
modified_by integer

Retrieve a component usage record

Returns the details of a specific component usage record.

1
2
3
4
http \
  GET \
  https://api.example.com/api/marketplace-component-usages/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.marketplace_component_usages import marketplace_component_usages_retrieve # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = marketplace_component_usages_retrieve.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: marketplace_component_usages_retrieve
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { marketplaceComponentUsagesRetrieve } from 'waldur-js-client';

try {
  const response = await marketplaceComponentUsagesRetrieve({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Name Type
field array

200 -

Field Type Description
uuid string (uuid)
created string (date-time)
description string
type string Unique internal name of the measured unit, for example floating_ip.
name string Display name for the measured unit, for example, Floating IP.
measured_unit string Unit of measurement, for example, GB.
usage integer
date string (date-time)
recurring boolean Reported value is reused every month until changed.
resource_name string
resource_uuid string (uuid)
offering_name string
offering_uuid string (uuid)
project_name string
project_uuid string
customer_name string
customer_uuid string
billing_period string (date)
modified_by integer

Other Actions

Set component usage for a resource

1
2
3
4
5
6
    Allows a service provider to report usage for one or more components of a specific resource.
    This endpoint is typically used by backend systems or agents to submit periodic usage data.

    - If a `plan_period` is provided, the usage is associated with that period.
    - If only a `resource` is provided, the system will determine the correct plan period based on the current date.
    - If a usage record for the same resource, component, and billing period already exists, it will be updated. Otherwise, a new record is created.

1
2
3
4
5
http \
  POST \
  https://api.example.com/api/marketplace-component-usages/set_usage/ \
  Authorization:"Token YOUR_API_TOKEN" \
  usages:='[]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.component_usage_create_request import ComponentUsageCreateRequest # (1)
from waldur_api_client.api.marketplace_component_usages import marketplace_component_usages_set_usage # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = ComponentUsageCreateRequest(
    usages=[]
)
response = marketplace_component_usages_set_usage.sync(
    client=client,
    body=body_data
)

print(response)
  1. Model Source: ComponentUsageCreateRequest
  2. API Source: marketplace_component_usages_set_usage
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { marketplaceComponentUsagesSetUsage } from 'waldur-js-client';

try {
  const response = await marketplaceComponentUsagesSetUsage({
  auth: "Token YOUR_API_TOKEN",
  body: {
    "usages": []
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Field Type Required Description
usages array of objects ✓ List of component usage items to report
usages.type string ✓ Type of the component
usages.amount string (decimal) ✓ Usage amount
usages.description string Optional description of usage
usages.recurring boolean Whether this usage is recurring
Constraints: default: False
plan_period string (uuid) UUID of the specific resource plan period for usage reporting
resource string (uuid) UUID of the resource for usage reporting (required if plan_period not provided)
date string (date-time) Date for usage reporting (staff and service providers for limit-based components). If not provided, current date is used.

201 - No response body

Set user-specific component usage

1
2
3
4
5
    Allows a service provider to report usage for a specific user associated with a resource's component.
    This is used for detailed, per-user usage tracking within a single resource.

    - If a user-specific usage record already exists for the given component usage, it will be updated.
    - Otherwise, a new record is created.

1
2
3
4
5
http \
  POST \
  https://api.example.com/api/marketplace-component-usages/a1b2c3d4-e5f6-7890-abcd-ef1234567890/set_user_usage/ \
  Authorization:"Token YOUR_API_TOKEN" \
  username="alice"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.component_user_usage_create_request import ComponentUserUsageCreateRequest # (1)
from waldur_api_client.api.marketplace_component_usages import marketplace_component_usages_set_user_usage # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = ComponentUserUsageCreateRequest(
    username="alice"
)
response = marketplace_component_usages_set_user_usage.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

print(response)
  1. Model Source: ComponentUserUsageCreateRequest
  2. API Source: marketplace_component_usages_set_user_usage
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { marketplaceComponentUsagesSetUserUsage } from 'waldur-js-client';

try {
  const response = await marketplaceComponentUsagesSetUserUsage({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  body: {
    "username": "alice"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required Description
usage string (decimal)
username string ✓
user string (uri)
date string (date-time) Date for usage reporting (staff and service providers for limit-based components). If not provided, current date is used.

201 - No response body