delopay 0.2.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The subscription models: subscriptions, their invoices, purchasable items,
//! and cost estimates.

use serde::Deserialize;
use serde_json::Value;

use crate::core::models::common::{
    Currency, IntentStatus, InvoiceStatus, PaymentMethodType, SubscriptionPeriodUnit,
    SubscriptionStatus,
};

/// A subscription, as returned by create / retrieve / update / list.
///
/// The confirm and create-and-confirm flows return
/// [`ConfirmSubscriptionResponse`] instead, which additionally carries the
/// billing-processor subscription ID and the buyer-approval `redirect_url`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionResponse {
    /// Unique subscription ID.
    pub id: String,
    /// Current lifecycle status.
    pub status: SubscriptionStatus,

    /// Your own reference for this subscription.
    #[serde(default)]
    pub merchant_reference_id: Option<String>,
    /// Plan the subscription is on.
    #[serde(default)]
    pub plan_id: Option<String>,
    /// Price the subscription is billed at.
    #[serde(default)]
    pub item_price_id: Option<String>,
    /// Shop (business profile) ID the subscription belongs to.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Short-lived token used by client SDKs to authenticate confirm calls.
    #[serde(default)]
    pub client_secret: Option<String>,
    /// Merchant account ID.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Coupon applied at creation, if any.
    #[serde(default)]
    pub coupon_code: Option<String>,
    /// Customer the subscription bills.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// Payment leg for the current billing cycle, once a charge was attempted.
    #[serde(default)]
    pub payment: Option<SubscriptionPaymentData>,
    /// Invoice for the current billing cycle.
    #[serde(default)]
    pub invoice: Option<SubscriptionInvoice>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Returned by the create-and-confirm and confirm subscription calls.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ConfirmSubscriptionResponse {
    /// Unique subscription ID.
    pub id: String,
    /// Current lifecycle status.
    pub status: SubscriptionStatus,

    /// Your own reference for this subscription.
    #[serde(default)]
    pub merchant_reference_id: Option<String>,
    /// Plan the subscription is on.
    #[serde(default)]
    pub plan_id: Option<String>,
    /// Price the subscription is billed at.
    #[serde(default)]
    pub item_price_id: Option<String>,
    /// Coupon applied, if any.
    #[serde(default)]
    pub coupon: Option<String>,
    /// Shop (business profile) ID the subscription belongs to.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Customer the subscription bills.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// Payment leg for the first billing cycle.
    #[serde(default)]
    pub payment: Option<SubscriptionPaymentData>,
    /// Invoice for the first billing cycle.
    #[serde(default)]
    pub invoice: Option<SubscriptionInvoice>,
    /// Subscription ID on the billing processor (Stripe Billing / PayPal).
    #[serde(default)]
    pub billing_processor_subscription_id: Option<String>,
    /// URL the customer must be redirected to in order to approve the
    /// subscription, for billing processors that require buyer approval (e.g.
    /// PayPal). `None` for processors that activate server-side.
    #[serde(default)]
    pub redirect_url: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Returned by `Subscriptions::pause`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PauseSubscriptionResponse {
    /// Unique subscription ID.
    pub id: String,
    /// Status after the pause took effect (or was scheduled).
    pub status: SubscriptionStatus,
    /// Your own reference for this subscription.
    #[serde(default)]
    pub merchant_reference_id: Option<String>,
    /// Shop (business profile) ID.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Merchant account ID.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Customer the subscription bills.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// ISO 8601 timestamp the subscription was (or will be) paused at.
    #[serde(default)]
    pub paused_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Returned by `Subscriptions::resume`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ResumeSubscriptionResponse {
    /// Unique subscription ID.
    pub id: String,
    /// Status after resuming.
    pub status: SubscriptionStatus,
    /// Your own reference for this subscription.
    #[serde(default)]
    pub merchant_reference_id: Option<String>,
    /// Shop (business profile) ID.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Merchant account ID.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Customer the subscription bills.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// ISO 8601 timestamp of the next billing cycle.
    #[serde(default)]
    pub next_billing_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Returned by `Subscriptions::cancel`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CancelSubscriptionResponse {
    /// Unique subscription ID.
    pub id: String,
    /// Status after the cancellation took effect (or was scheduled).
    pub status: SubscriptionStatus,
    /// Your own reference for this subscription.
    #[serde(default)]
    pub merchant_reference_id: Option<String>,
    /// Shop (business profile) ID.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Merchant account ID.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Customer the subscription billed.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// ISO 8601 timestamp the subscription was (or will be) cancelled at.
    #[serde(default)]
    pub cancelled_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Payment leg attached to a subscription's current billing cycle, present
/// once a charge has been attempted.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionPaymentData {
    /// The payment intent charging this cycle.
    pub payment_id: String,
    /// Status of that payment intent.
    pub status: IntentStatus,
    /// Amount in minor units.
    #[serde(default)]
    pub amount: Option<i64>,
    /// Three-letter ISO 4217 currency code.
    #[serde(default)]
    pub currency: Option<Currency>,
    /// Next action to drive on the client (redirect, render QR, etc.).
    #[serde(default)]
    pub next_action: Option<Value>,
    /// Client secret for client-side confirmation (do not log or share).
    #[serde(default)]
    pub client_secret: Option<String>,
    /// Gateway error code, if the charge failed.
    #[serde(default)]
    pub error_code: Option<String>,
    /// Human-readable error message, if the charge failed.
    #[serde(default)]
    pub error_message: Option<String>,
    /// Payment method sub-type used.
    #[serde(default)]
    pub payment_method_type: Option<PaymentMethodType>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A single invoice raised for one billing cycle of a subscription.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionInvoice {
    /// Unique invoice ID.
    pub id: String,
    /// The subscription this invoice bills.
    pub subscription_id: String,
    /// Amount in minor units.
    pub amount: i64,
    /// Three-letter ISO 4217 currency code.
    pub currency: Currency,
    /// Invoice status.
    pub status: InvoiceStatus,
    /// Merchant account ID.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Shop (business profile) ID.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Customer billed.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// Payment intent charging this invoice, once one exists.
    #[serde(default)]
    pub payment_intent_id: Option<String>,
    /// Payment method charged.
    #[serde(default)]
    pub payment_method_id: Option<String>,
    /// This invoice's ID on the billing processor (Stripe Billing / PayPal).
    #[serde(default)]
    pub billing_processor_invoice_id: Option<String>,
    /// Connector (billing processor) the invoice was raised through.
    #[serde(default)]
    pub provider_name: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A purchasable price option for a subscription item (plan or addon).
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionItemPrice {
    /// Unique price ID (pass as `item_price_id` when creating a subscription).
    pub price_id: String,
    /// Amount in minor units.
    pub amount: i64,
    /// Three-letter ISO 4217 currency code.
    pub currency: Currency,
    /// Plan or addon ID this price belongs to.
    #[serde(default)]
    pub item_id: Option<String>,
    /// Billing interval unit (`"Day"`, `"Week"`, `"Month"`, `"Year"`).
    #[serde(default)]
    pub interval: Option<SubscriptionPeriodUnit>,
    /// Number of interval units per billing cycle.
    #[serde(default)]
    pub interval_count: Option<i64>,
    /// Trial length, when the price includes one.
    #[serde(default)]
    pub trial_period: Option<i64>,
    /// Unit of `trial_period`.
    #[serde(default)]
    pub trial_period_unit: Option<SubscriptionPeriodUnit>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A subscription item (plan or addon) with its available prices, as returned
/// by `Subscriptions::items`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionItem {
    /// Unique item ID.
    pub item_id: String,
    /// Display name.
    pub name: String,
    /// Description, when set.
    #[serde(default)]
    pub description: Option<String>,
    /// Available prices for this item. Named `price_id` on the wire.
    #[serde(default, rename = "price_id")]
    pub prices: Vec<SubscriptionItemPrice>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A single line of a subscription cost estimate.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionLineItem {
    /// Item this line bills.
    pub item_id: String,
    /// Item type, e.g. `"plan"`, `"addon"`.
    pub item_type: String,
    /// Line description.
    #[serde(default)]
    pub description: Option<String>,
    /// Amount in minor units.
    pub amount: i64,
    /// Three-letter ISO 4217 currency code.
    pub currency: Currency,
    /// Quantity billed.
    #[serde(default)]
    pub quantity: Option<i64>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Cost estimate for a subscription before creating it, as returned by
/// `Subscriptions::estimate`.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SubscriptionEstimateResponse {
    /// Total amount in minor units.
    pub amount: i64,
    /// Three-letter ISO 4217 currency code.
    pub currency: Currency,
    /// Plan estimated.
    #[serde(default)]
    pub plan_id: Option<String>,
    /// Price estimated.
    #[serde(default)]
    pub item_price_id: Option<String>,
    /// Coupon applied to the estimate.
    #[serde(default)]
    pub coupon_code: Option<String>,
    /// Customer the estimate was computed for.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// Line-by-line breakdown.
    #[serde(default)]
    pub line_items: Vec<SubscriptionLineItem>,
    /// Billing interval unit, when the connector exposes it.
    #[serde(default)]
    pub interval: Option<SubscriptionPeriodUnit>,
    /// Number of interval units per cycle, when known.
    #[serde(default)]
    pub interval_count: Option<i64>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}