| Crates.io | lago-types |
| lib.rs | lago-types |
| version | 0.1.18 |
| created_at | 2025-07-16 09:28:34.147838+00 |
| updated_at | 2026-01-07 13:42:59.399556+00 |
| description | Types definitions for Lago API |
| homepage | |
| repository | https://github.com/getlago/lago-rust-client |
| max_upload_size | |
| id | 1755222 |
| size | 284,192 |
A comprehensive type library for the Lago billing system, providing Rust data structures for API requests, responses, and domain models.
This crate contains all the type definitions needed to interact with the Lago billing API, including:
Customer, CustomerUsage, Invoice, CreditNote, Coupon, AppliedCoupon, ActivityLogObject, ApiLogObject, UsageThreshold, EventFromStr implementations for enums to parse from string representationsThe library provides convenient FromStr implementations for all enums, allowing easy conversion from string representations to typed enum values. This is particularly useful when working with external APIs or user input.
use std::str::FromStr;
use lago_types::models::{InvoiceType};
// Using FromStr::from_str()
let invoice_type = InvoiceType::from_str("subscription").unwrap();
assert_eq!(invoice_type, InvoiceType::Subscription);
// Error handling for invalid values
let result: Result<InvoiceType, _> = "invalid_type".parse();
assert!(result.is_err());
Add this crate to your Cargo.toml:
[dependencies]
lago-types = { path = "../lago-types" }
use std::str::FromStr;
use lago_types::{
models::{Customer, Invoice, InvoicePaymentStatus, InvoiceType},
requests::ListInvoicesRequest,
filters::InvoiceFilters,
models::PaginationParams,
};
// Parse enum values from strings
let status: InvoiceStatus = "finalized".parse().unwrap();
let payment_status: InvoicePaymentStatus = "pending".parse().unwrap();
let invoice_type = InvoiceType::from_str("subscription").unwrap();
// Create a request to list invoices with filters
let request = ListInvoicesRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(20)
)
.with_filters(
InvoiceFilters::new()
.with_customer_id("customer_123".to_string())
.with_status(status)
.with_payment_status(payment_status)
.with_invoice_type(invoice_type)
);
// Convert to query parameters
let params = request.to_query_params();
Work with invoices including creation, updates, and management:
use lago_types::requests::invoice::{
// Preview types
BillingTime, InvoicePreviewInput, InvoicePreviewRequest,
InvoicePreviewCustomer, InvoicePreviewCoupon, InvoicePreviewSubscriptions,
// Create types
CreateInvoiceInput, CreateInvoiceFeeInput, CreateInvoiceRequest,
// Update types
UpdateInvoiceInput, UpdateInvoiceMetadataInput, UpdateInvoiceRequest,
// List types
ListCustomerInvoicesRequest,
// Action types
RefreshInvoiceRequest, DownloadInvoiceRequest, RetryInvoiceRequest,
RetryInvoicePaymentRequest, VoidInvoiceRequest,
};
// Create a one-off invoice
let fee = CreateInvoiceFeeInput::new("setup_fee".to_string(), 1.0)
.with_unit_amount_cents(9900)
.with_description("One-time setup fee".to_string())
.with_tax_codes(vec!["vat_20".to_string()]);
let input = CreateInvoiceInput::new(
"customer_123".to_string(),
"USD".to_string(),
vec![fee],
);
let request = CreateInvoiceRequest::new(input);
// Update an invoice
let metadata = UpdateInvoiceMetadataInput::new(
"payment_ref".to_string(),
"REF-12345".to_string(),
);
let input = UpdateInvoiceInput::new()
.with_payment_status("succeeded".to_string())
.with_metadata(vec![metadata]);
let request = UpdateInvoiceRequest::new("invoice-lago-id".to_string(), input);
// List customer invoices
let request = ListCustomerInvoicesRequest::new("customer_123".to_string())
.with_pagination(PaginationParams::new().with_per_page(20));
// Refresh a draft invoice
let request = RefreshInvoiceRequest::new("invoice-lago-id".to_string());
// Download invoice PDF
let request = DownloadInvoiceRequest::new("invoice-lago-id".to_string());
// Retry failed invoice finalization
let request = RetryInvoiceRequest::new("invoice-lago-id".to_string());
// Retry failed payment
let request = RetryInvoicePaymentRequest::new("invoice-lago-id".to_string());
// Void a finalized invoice
let request = VoidInvoiceRequest::new("invoice-lago-id".to_string());
Preview an invoice before creating it:
use lago_types::requests::invoice::{
BillingTime, InvoicePreviewInput, InvoicePreviewRequest,
InvoicePreviewCustomer, InvoicePreviewCoupon, InvoicePreviewSubscriptions,
};
// Preview for an existing customer with a new subscription
let preview = InvoicePreviewInput::for_customer("customer_123".to_string())
.with_plan_code("startup".to_string())
.with_billing_time(BillingTime::Calendar);
let request = InvoicePreviewRequest::new(preview);
// Preview with inline customer details
let customer = InvoicePreviewCustomer::new()
.with_name("New Customer".to_string())
.with_currency("USD".to_string());
let preview = InvoicePreviewInput::new(customer)
.with_plan_code("enterprise".to_string())
.with_subscription_at("2024-01-01T00:00:00Z".to_string());
// Preview with coupons
let coupon = InvoicePreviewCoupon::new("DISCOUNT20".to_string())
.with_percentage("20".to_string());
let preview = InvoicePreviewInput::for_customer("customer_123".to_string())
.with_plan_code("startup".to_string())
.with_coupons(vec![coupon]);
// Preview for existing subscriptions with plan upgrade
let subscriptions = InvoicePreviewSubscriptions::new(vec!["sub_123".to_string()])
.with_plan_code("enterprise".to_string());
let preview = InvoicePreviewInput::for_customer("customer_123".to_string())
.with_subscriptions(subscriptions);
### Activity Logs
Fetch activity logs:
```rust
use std::str::FromStr;
use lago_types::{
models::{ActivitySource, PaginationParams},
requests::activity_log::{ListActivityLogsRequest, GetActivityLogRequest},
filters::activity_log::ActivityLogFilters,
};
// Parse activity source from string
let source = ActivitySource::from_str("api").unwrap();
// Create a request to list activity logs with filters
let request = ListActivityLogsRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(50)
)
.with_filters(
ActivityLogFilters::new()
.with_activity_types(vec!["invoice.created".to_string()])
.with_activity_sources(vec![ActivitySource::Api, ActivitySource::Front])
.with_user_emails(vec!["admin@example.com".to_string()])
.with_resource_types(vec!["Invoice".to_string()])
.with_date_range("2025-01-01".to_string(), "2025-01-31".to_string())
);
// Get a specific activity log by activity ID
let get_request = GetActivityLogRequest::new("activity-uuid".to_string());
Fetch API logs:
use std::str::FromStr;
use lago_types::{
models::{HttpMethod, HttpStatus, StatusOutcome, PaginationParams},
requests::api_log::{ListApiLogsRequest, GetApiLogRequest},
filters::api_log::ApiLogFilters,
};
// Parse HTTP method from string
let method = HttpMethod::from_str("post").unwrap();
// Create a request to list API logs with filters
let request = ListApiLogsRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(50)
)
.with_filters(
ApiLogFilters::new()
.with_http_methods(vec![HttpMethod::Post, HttpMethod::Put])
.with_http_statuses(vec![
HttpStatus::Outcome(StatusOutcome::Failed),
HttpStatus::Code(500)
])
.with_api_version("v1".to_string())
.with_date_range("2025-01-01".to_string(), "2025-01-31".to_string())
);
// Get a specific API log by request ID
let get_request = GetApiLogRequest::new("request-uuid".to_string());
Work with applied coupons:
use lago_types::{
filters::applied_coupon::AppliedCouponFilter,
models::{AppliedCouponStatus, AppliedCouponFrequency, PaginationParams},
requests::applied_coupon::{ApplyCouponInput, ApplyCouponRequest, ListAppliedCouponsRequest},
};
// Create input to apply a coupon to a customer
let apply_input = ApplyCouponInput::new(
"customer_123".to_string(),
"WELCOME10".to_string()
);
// Apply with a fixed amount discount
let apply_input = ApplyCouponInput::new("customer_123".to_string(), "DISCOUNT50".to_string())
.with_fixed_amount(5000, "USD".to_string())
.with_frequency(AppliedCouponFrequency::Once);
// Apply with a percentage discount
let apply_input = ApplyCouponInput::new("customer_123".to_string(), "SAVE20".to_string())
.with_percentage_rate("20".to_string())
.with_frequency(AppliedCouponFrequency::Recurring)
.with_frequency_duration(3); // Apply for 3 billing periods
let request = ApplyCouponRequest::new(apply_input);
// Create a request to list applied coupons with filters
let list_request = ListAppliedCouponsRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(50)
)
.with_filters(
AppliedCouponFilter::new()
.with_status(AppliedCouponStatus::Active)
.with_external_customer_id("customer_123".to_string())
.with_coupon_codes(vec!["WELCOME10".to_string(), "SAVE20".to_string()])
);
// Convert to query parameters
let params = list_request.to_query_params();
Work with coupon definitions:
use lago_types::{
models::{CouponExpiration, CouponFrequency, PaginationParams},
requests::coupon::{
CreateCouponInput, CreateCouponRequest, DeleteCouponRequest,
GetCouponRequest, ListCouponsRequest, UpdateCouponInput, UpdateCouponRequest,
},
};
// Create a percentage-based coupon
let coupon = CreateCouponInput::percentage(
"Welcome 10% Discount".to_string(),
"WELCOME10".to_string(),
"10".to_string(),
CouponFrequency::Once,
CouponExpiration::NoExpiration,
)
.with_reusable(true);
let request = CreateCouponRequest::new(coupon);
// Create a fixed amount coupon with recurring application
let coupon = CreateCouponInput::fixed_amount(
"Summer $50 Off".to_string(),
"SUMMER50".to_string(),
5000, // $50.00 in cents
"USD".to_string(),
CouponFrequency::Recurring,
CouponExpiration::NoExpiration,
)
.with_frequency_duration(3) // Apply for 3 billing periods
.with_limited_plans(vec!["startup".to_string(), "professional".to_string()]);
let request = CreateCouponRequest::new(coupon);
// List coupons with pagination
let list_request = ListCouponsRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(20)
);
let params = list_request.to_query_params();
// Get a specific coupon
let get_request = GetCouponRequest::new("WELCOME10".to_string());
// Update an existing coupon
let update_input = UpdateCouponInput::new()
.with_name("Welcome 15% Discount".to_string())
.with_percentage_rate("15".to_string())
.with_reusable(false);
let update_request = UpdateCouponRequest::new("WELCOME10".to_string(), update_input);
// Delete a coupon
let delete_request = DeleteCouponRequest::new("SUMMER50".to_string());
Send, retrieve, and list usage events:
use lago_types::{
models::PaginationParams,
requests::event::{CreateEventInput, CreateEventRequest, GetEventRequest, ListEventsRequest},
};
use serde_json::json;
// Create a usage event for a customer
let event = CreateEventInput::for_customer(
"transaction_123".to_string(),
"customer_456".to_string(),
"api_calls".to_string(),
)
.with_properties(json!({"calls": 150}))
.with_timestamp(1705312200);
let request = CreateEventRequest::new(event);
// Create a usage event for a subscription
let event = CreateEventInput::for_subscription(
"transaction_456".to_string(),
"subscription_789".to_string(),
"storage_gb".to_string(),
)
.with_properties(json!({"gb": 50.5}))
.with_precise_total_amount_cents(1234567);
let request = CreateEventRequest::new(event);
// Get a specific event by transaction ID
let get_request = GetEventRequest::new("transaction_123".to_string());
// List events with filters
let list_request = ListEventsRequest::new()
.with_pagination(PaginationParams::new().with_page(1).with_per_page(50))
.with_external_subscription_id("subscription_123".to_string())
.with_code("api_calls".to_string())
.with_timestamp_range(
"2024-01-01T00:00:00Z".to_string(),
"2024-01-31T23:59:59Z".to_string(),
);
// Convert to query parameters
let params = list_request.to_query_params();
Work with credit notes:
use lago_types::{
models::{CreditNoteReason, CreditNoteRefundStatus, PaginationParams},
requests::credit_note::{
CreateCreditNoteInput, CreateCreditNoteItemInput, CreateCreditNoteRequest,
GetCreditNoteRequest, ListCreditNotesRequest, UpdateCreditNoteInput, UpdateCreditNoteRequest,
},
filters::credit_note::CreditNoteFilter,
};
// List credit notes with filters
let request = ListCreditNotesRequest::new()
.with_pagination(
PaginationParams::new()
.with_page(1)
.with_per_page(20)
)
.with_filters(
CreditNoteFilter::new()
.with_external_customer_id("customer_123".to_string())
.with_reason(CreditNoteReason::Other)
.with_date_range("2024-01-01".to_string(), "2024-12-31".to_string())
);
let params = request.to_query_params();
// Get a specific credit note
let get_request = GetCreditNoteRequest::new("credit-note-uuid".to_string());
// Create a credit note
let items = vec![
CreateCreditNoteItemInput::new("fee_lago_id".to_string(), 1000),
];
let input = CreateCreditNoteInput::new(
"invoice_lago_id".to_string(),
CreditNoteReason::Other,
1000, // credit_amount_cents
0, // refund_amount_cents
items,
)
.with_description("Credit for billing adjustment".to_string());
let create_request = CreateCreditNoteRequest::new(input);
// Update a credit note's refund status
let update_input = UpdateCreditNoteInput::new()
.with_refund_status(CreditNoteRefundStatus::Succeeded);
let update_request = UpdateCreditNoteRequest::new("credit-note-uuid".to_string(), update_input);
Retrieve current usage data for a customer's subscription:
use lago_types::requests::customer_usage::GetCustomerCurrentUsageRequest;
// Get current usage for a customer's subscription
let request = GetCustomerCurrentUsageRequest::new(
"customer_123".to_string(),
"subscription_456".to_string(),
);
// Get usage without applying taxes
let request = GetCustomerCurrentUsageRequest::new(
"customer_123".to_string(),
"subscription_456".to_string(),
)
.with_apply_taxes(false);
// Convert to query parameters
let params = request.to_query_params();
models/ - Core domain models and data structuresrequests/ - Request types for API operationsresponses/ - Response types from API endpointsfilters/ - Filter builders for list operationserror.rs - Error types and handlingBefore publishing a release
cargo check
cargo test
cargo doc --no-deps --open
cargo package
Run the release
cargo login API_KEY
cargo publish
This project is licensed under the MIT License - see the LICENSE file for details.