Rust SDK

cargo add alguna
cargo add tokio --features macros,rt-multi-thread

use alguna::prelude::*;
use alguna::ApiClientBuilder;

fn client() -> Result<Alguna, ApiError> {
    // Reads the API key from ALGUNA_API_KEY when you do not call api_key.
    ApiClientBuilder::default()
        .api_version("2026-04-01") // recommended: pin the version you integrate against
        .build()
}

use alguna::prelude::*;
use alguna::ApiClientBuilder;

#[tokio::main]
async fn main() -> Result<(), ApiError> {
    let client = ApiClientBuilder::default().build()?;

    // 1. Create a customer
    let customer = client
        .customers
        .create(
            &CreateCustomerRequest {
                name: "Acme Corp".to_string(),
                currency: "USD".to_string(),
                ..Default::default()
            },
            None,
        )
        .await?;

    // 2. Start a subscription from a plan you made in the dashboard or API
    let subscription = client
        .subscriptions
        .create(
            &CreateSubscriptionRequest {
                customer_id: customer.id.clone(),
                plan_id: Some("<plan_id>".to_string()),
                auto_activate: Some(true),
                ..Default::default()
            },
            None,
        )
        .await?;
    println!("subscription {}", subscription.id);

    // 3. Issue a one-off invoice
    let invoice = client
        .invoices
        .create(
            &CreateInvoiceRequest {
                customer_id: Some(customer.id.clone()),
                currency: Some("USD".to_string()),
                line_items: Some(vec![CreateInvoiceLineItemRequest {
                    description: Some("Onboarding".to_string()),
                    unit_price: "500.00".to_string(),
                    quantity: "1".to_string(),
                    ..Default::default()
                }]),
                ..Default::default()
            },
            None,
        )
        .await?;
    println!("invoice {}", invoice.id);

    // 4. Open a customer portal session so the customer can pay and manage billing
    let session = client
        .portal
        .create_session(
            &CreateCustomerPortalSessionRequest {
                customer_id: Some(customer.id.clone()),
                ..Default::default()
            },
            None,
        )
        .await?;
    println!("{}", session.url); // send the customer here before session.expires_at
    Ok(())
}

use alguna::prelude::*;

async fn list_metered(client: &Alguna) -> Result<(), ApiError> {
    let filter = ProductsListQueryRequest {
        fee_type: Some(vec![ListProductsRequestFeeTypeItem::Metered]),
        ..Default::default()
    };
    for product in client.products.list(&filter, None).await?.data {
        println!("{}", product.name);
    }
    Ok(())
}

use alguna::prelude::*;
use futures::StreamExt;

async fn every_customer(client: &Alguna) -> Result<(), ApiError> {
    let mut customers = client
        .customers
        .list_paginated(&CustomersListQueryRequest::default(), None)
        .await?;
    while let Some(customer) = customers.next().await {
        let customer: CustomerResponse = customer?;
        println!("{}", customer.name);
    }
    Ok(())
}

use alguna::prelude::*;

async fn save_pdf(client: &Alguna, invoice_id: &str) -> Result<(), Box<dyn std::error::Error>> {
    let pdf = client.invoices.generate_pdf(invoice_id, None).await?;
    std::fs::write("invoice.pdf", pdf.collect().await?)?;
    Ok(())
}

use alguna::prelude::*;

async fn find(client: &Alguna, id: &str) -> Result<Option<CustomerResponse>, ApiError> {
    match client.customers.get(id, None).await {
        Ok(customer) => Ok(Some(customer)),
        Err(ApiError::NotFoundError { .. }) => Ok(None),
        Err(error) => {
            // status(): the HTTP status, if the API answered. detail(): its reason.
            eprintln!(
                "{:?} {:?} timeout={}",
                error.status(),
                error.detail(),
                error.is_timeout()
            );
            Err(error)
        }
    }
}

use alguna::prelude::*;

async fn create_once(client: &Alguna, request: &CreateCustomerRequest) -> Result<(), ApiError> {
    let options = RequestOptions::new().idempotency_key("create-customer-acme");
    client.customers.create(request, Some(options)).await?;
    Ok(())
}

use alguna::ApiClientBuilder;
use std::time::Duration;

let client = ApiClientBuilder::new("https://api.sandbox.alguna.io") // default: https://api.alguna.io
    .api_key("<key_id>.<key_secret>")  // default: the ALGUNA_API_KEY environment variable
    .api_version("2026-04-01")         // default: the version this release targets
    .timeout(Duration::from_secs(30))  // each attempt; default: 60 seconds
    .max_retries(4)                    // default: 2
    .build()?;