feat: add CreditNote and CustomerBalanceTransaction

Customer balance transactions are used to track changes to the
customer's balance. Credit Notes are a way of attaching a balance change
to an invoice.

src/ids.rs

@@ -498,6 +498,9 @@ def_id!(CheckoutSessionId, "cs_");
 def_id!(CheckoutSessionItemId: String); // TODO: Figure out what prefix this id has
 def_id!(ConnectCollectionTransferId, "connct_");
 def_id!(CouponId: String); // N.B. A coupon id can be user-provided so can be any arbitrary string
+def_id!(CreditNoteId, "cn_");
+def_id!(CreditNoteLineItemId, "cnli_");
+def_id!(CustomerBalanceTransactionId, "cbtxn_");
 def_id!(CustomerId, "cus_");
 def_id!(DiscountId, "di_");
 def_id!(DisputeId, "dp_" | "du_");

src/resources.rs

@@ -39,6 +39,8 @@ mod webhook_events;
 #[path = "resources"]
 #[cfg(feature = "billing")]
 mod billing {
+    pub mod credit_note_ext;
+    pub mod customer_balance_transaction_ext;
     pub mod invoice_ext;
     pub mod line_item_ext;
     pub mod subscription_ext;
@@ -175,6 +177,7 @@ pub use {
 #[cfg(feature = "billing")]
 pub use {
     billing::{
+        customer_balance_transaction_ext::*,
         invoice_ext::*,
         line_item_ext::*,
         subscription_ext::*,
@@ -184,6 +187,9 @@ pub use {
         billing_portal_session::*,
         billing_portal_configuration::*,
         coupon::*,
+        credit_note::*,
+        credit_note_line_item::*,
+        customer_balance_transaction::*,
         discount::*,
         invoice::*,
         invoice_payment_method_options_acss_debit::*,

src/resources/credit_note_ext.rs

@@ -0,0 +1,12 @@
+use crate::client::{Client, Response};
+use crate::ids::CreditNoteId;
+use crate::resources::CreditNote;
+
+impl CreditNote {
+    /// Marks a credit note as void.
+    ///
+    /// You can only void a credit note if the associated invoice is open.
+    pub fn void(client: &Client, id: &CreditNoteId) -> Response<CreditNote> {
+        client.post(&format!("/credit_notes/{}/void", id))
+    }
+}

src/resources/customer_balance_transaction_ext.rs

@@ -0,0 +1,137 @@
+use serde::Serialize;
+
+use crate::client::{Client, Response};
+use crate::ids::{CustomerBalanceTransactionId, CustomerId};
+use crate::params::{Expand, List, Metadata, Paginable};
+use crate::resources::{Currency, Customer, CustomerBalanceTransaction};
+
+/// The parameters for `CustomerBalanceTransaction::list`.
+#[derive(Clone, Debug, Serialize, Default)]
+pub struct ListCustomerBalanceTransactions<'a> {
+    /// Specifies which fields in the response should be expanded.
+    #[serde(skip_serializing_if = "Expand::is_empty")]
+    pub expand: &'a [&'a str],
+
+    /// A cursor for use in pagination.
+    ///
+    /// `ending_before` is an object ID that defines your place in the list.
+    /// For instance, if you make a list request and receive 100 objects,
+    /// starting with `obj_bar`, your subsequent call can include
+    /// `ending_before=obj_bar` in order to fetch the previous page of the list.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ending_before: Option<CustomerBalanceTransactionId>,
+
+    /// A limit on the number of objects to be returned.
+    ///
+    /// Limit can range between 1 and 100, and the default is 10.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit: Option<u64>,
+
+    /// A cursor for use in pagination.
+    ///
+    /// `starting_after` is an object ID that defines your place in the list.
+    /// For instance, if you make a list request and receive 100 objects,
+    /// ending with `obj_foo`, your subsequent call can include
+    /// `starting_after=obj_foo` in order to fetch the next page of the list.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub starting_after: Option<CustomerBalanceTransactionId>,
+}
+
+impl Paginable for ListCustomerBalanceTransactions<'_> {
+    type O = CustomerBalanceTransaction;
+    fn set_last(&mut self, item: Self::O) {
+        self.starting_after = Some(item.id);
+    }
+}
+
+/// The parameters that can be used when creating or updating a [`CustomerBalanceTransaction`].
+#[derive(Clone, Debug, Serialize)]
+pub struct CreateCustomerBalanceTransaction<'a> {
+    /// The integer amount in cents to apply to the customer’s credit balance.
+    pub amount: i64,
+    /// Three-letter ISO currency code, in lowercase.
+    ///
+    /// Must be a supported currency. Specifies the invoice_credit_balance that this
+    /// transaction will apply to. If the customer’s currency is not set, it will be
+    /// updated to this value.
+    pub currency: Currency,
+    /// An arbitrary string attached to the object. Often useful for displaying to users.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<&'a str>,
+    /// Set of key-value pairs that you can attach to an object.
+    ///
+    /// This can be useful for storing additional information about the object in a
+    /// structured format. Individual keys can be unset by posting an empty value to
+    /// them. All keys can be unset by posting an empty value to metadata.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Metadata>,
+}
+
+impl CreateCustomerBalanceTransaction<'_> {
+    pub fn new(amount: i64, currency: Currency) -> Self {
+        Self { amount, currency, description: Default::default(), metadata: Default::default() }
+    }
+}
+
+/// The parameters that can be used when creating or updating a [`CustomerBalanceTransaction`].
+///
+/// Only the description and metadata fields can be updated.
+#[derive(Clone, Debug, Default, Serialize)]
+pub struct UpdateCustomerBalanceTransaction<'a> {
+    /// An arbitrary string attached to the object. Often useful for displaying to users.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<&'a str>,
+    /// Set of key-value pairs that you can attach to an object.
+    ///
+    /// This can be useful for storing additional information about the object in a
+    /// structured format. Individual keys can be unset by posting an empty value to
+    /// them. All keys can be unset by posting an empty value to metadata.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Metadata>,
+}
+
+impl Customer {
+    /// List all of a customer's balance transactions.
+    pub fn list_balance_transactions(
+        client: &Client,
+        customer_id: &CustomerId,
+        params: ListCustomerBalanceTransactions<'_>,
+    ) -> Response<List<CustomerBalanceTransaction>> {
+        client.get_query(&format!("/customers/{}/balance_transactions", customer_id), &params)
+    }
+
+    /// Create a new customer balance transaction.
+    pub fn create_balance_transaction(
+        client: &Client,
+        customer_id: &CustomerId,
+        params: CreateCustomerBalanceTransaction<'_>,
+    ) -> Response<CustomerBalanceTransaction> {
+        client.post_form(&format!("/customers/{}/balance_transactions", customer_id), &params)
+    }
+
+    /// Retrieve a customer balance transaction.
+    pub fn retrieve_balance_transaction(
+        client: &Client,
+        customer_id: &CustomerId,
+        id: &CustomerBalanceTransactionId,
+        expand: &[&str],
+    ) -> Response<CustomerBalanceTransaction> {
+        client.get_query(
+            &format!("/customers/{}/balance_transactions/{}", customer_id, id),
+            &Expand { expand },
+        )
+    }
+
+    /// Update a customer balance transaction.
+    ///
+    /// Only the description and metadata fields can be updated.
+    pub fn update_balance_transaction(
+        client: &Client,
+        customer_id: &CustomerId,
+        id: &CustomerBalanceTransactionId,
+        params: UpdateCustomerBalanceTransaction<'_>,
+    ) -> Response<CustomerBalanceTransaction> {
+        client
+            .post_form(&format!("/customers/{}/balance_transactions/{}", customer_id, id), &params)
+    }
+}

src/resources/generated.rs

@@ -69,6 +69,9 @@ pub mod billing {
     pub mod billing_portal_configuration;
     pub mod billing_portal_session;
     pub mod coupon;
+    pub mod credit_note;
+    pub mod credit_note_line_item;
+    pub mod customer_balance_transaction;
     pub mod discount;
     pub mod invoice;
     pub mod invoice_payment_method_options_acss_debit;