From dc82e59cd6e4e2f84b311d8e38c1299e96f5726d Mon Sep 17 00:00:00 2001 From: Eric Seppanen Date: Thu, 2 Mar 2023 18:32:25 -0800 Subject: [PATCH] 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 | 3 + src/resources.rs | 6 + src/resources/credit_note_ext.rs | 12 ++ .../customer_balance_transaction_ext.rs | 137 ++++++++++++++++++ src/resources/generated.rs | 3 + 5 files changed, 161 insertions(+) create mode 100644 src/resources/credit_note_ext.rs create mode 100644 src/resources/customer_balance_transaction_ext.rs diff --git a/src/ids.rs b/src/ids.rs index 39621b444..a1fbf7584 100644 --- a/src/ids.rs +++ b/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_"); diff --git a/src/resources.rs b/src/resources.rs index d39756f34..0f16b93a1 100644 --- a/src/resources.rs +++ b/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::*, diff --git a/src/resources/credit_note_ext.rs b/src/resources/credit_note_ext.rs new file mode 100644 index 000000000..48c85d573 --- /dev/null +++ b/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 { + client.post(&format!("/credit_notes/{}/void", id)) + } +} diff --git a/src/resources/customer_balance_transaction_ext.rs b/src/resources/customer_balance_transaction_ext.rs new file mode 100644 index 000000000..0b5a4875a --- /dev/null +++ b/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, + + /// 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, + + /// 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, +} + +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, +} + +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, +} + +impl Customer { + /// List all of a customer's balance transactions. + pub fn list_balance_transactions( + client: &Client, + customer_id: &CustomerId, + params: ListCustomerBalanceTransactions<'_>, + ) -> Response> { + client.get_query(&format!("/customers/{}/balance_transactions", customer_id), ¶ms) + } + + /// Create a new customer balance transaction. + pub fn create_balance_transaction( + client: &Client, + customer_id: &CustomerId, + params: CreateCustomerBalanceTransaction<'_>, + ) -> Response { + client.post_form(&format!("/customers/{}/balance_transactions", customer_id), ¶ms) + } + + /// Retrieve a customer balance transaction. + pub fn retrieve_balance_transaction( + client: &Client, + customer_id: &CustomerId, + id: &CustomerBalanceTransactionId, + expand: &[&str], + ) -> Response { + 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 { + client + .post_form(&format!("/customers/{}/balance_transactions/{}", customer_id, id), ¶ms) + } +} diff --git a/src/resources/generated.rs b/src/resources/generated.rs index 028076a0b..8ab7608a9 100644 --- a/src/resources/generated.rs +++ b/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;