Partial Usage Reference¶
Partial usage endpoints manage unresolved resources created by user-key usage logging when spendware cannot fully resolve project, customer, or provider context at ingest time.
Endpoint Families¶
| Family | Raw Endpoints | Python SDK | TypeScript SDK |
|---|---|---|---|
| Partial projects | /api/v1/partial/projects |
client.partial_usage.list_projects(), get_project(), delete_project(), finalize_project() |
client.partialUsage.listProjects(), getProject(), deleteProject(), finalizeProject() |
| Partial customers | /api/v1/partial/customers |
client.partial_usage.list_customers(), get_customer(), delete_customer(), finalize_customer() |
client.partialUsage.listCustomers(), getCustomer(), deleteCustomer(), finalizeCustomer() |
| Partial providers | /api/v1/partial/providers |
client.partial_usage.list_providers(), get_provider(), delete_provider(), finalize_provider() |
client.partialUsage.listProviders(), getProvider(), deleteProvider(), finalizeProvider() |
Create Partials¶
Partials are created by logging usage to /api/v1/usage/log with a user API key when no concrete resource can be resolved. The request must include these external IDs:
project_external_id.customer_external_id.provider_external_id.
Customer-key logging does not create partial resources because the customer key already identifies the runtime customer context.
Finalize Payloads¶
Project finalization accepts title, currency, and optional external_id.
Customer finalization accepts title, currency, optional project_id, and optional external_id.
Provider finalization accepts provider/model identity, pricing fields, optional external_id, currency, and optional effective_date. Provider finalization is an administrative workflow and can require the platform usage-operations permission.
Analytics¶
Usage queries default to finalized usage only. Set partials_mode to include_eligible_partials when a report should include eligible partial usage that has not yet been finalized.
{
"project_ids": ["PROJECT_ID"],
"partials_mode": "include_eligible_partials"
}
Examples¶
curl "$SPENDWARE_BASE_URL/api/v1/partial/customers?is_resolved=false" \
-H "Authorization: Bearer $SPENDWARE_API_KEY"
curl "$SPENDWARE_BASE_URL/api/v1/partial/end-customers/PARTIAL_CUSTOMER_ID/finalize" \
-H "Authorization: Bearer $SPENDWARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Customer A","currency":"USD","project_id":"PROJECT_ID","external_id":"customer-a"}'
partials = client.partial_usage.list_customers()
partial_id = partials["data"][0]["id"]
finalized = client.partial_usage.finalize_customer(
partial_id,
{
"title": "Customer A",
"currency": "USD",
"project_id": "PROJECT_ID",
"external_id": "customer-a",
},
)
print(finalized)
const partials = await client.partialUsage.listCustomers();
const partial = (partials.data as Array<{ id: string }>)[0];
const finalized = await client.partialUsage.finalizeCustomer(partial.id, {
title: "Customer A",
currency: "USD",
project_id: "PROJECT_ID",
external_id: "customer-a",
});
console.log(finalized);
Use the OpenAPI-rendered Backend API page for complete schemas and response models.