square_api_client/api/
gift_cards_api.rs

1//! Create and access gift cards and link customers to gift cards.
2//!
3//! Square gift cards enable sellers to boost sales and attract new customers. Sellers can easily
4//! sell, redeem, track, and reload Square gift cards.
5//!
6//! Developers can use the Gift Cards API to integrate Square gift cards into third-party
7//! applications. In addition, developers can use the Gift Card Activities API to create gift card
8//! activities, such as activate a gift card, add funds to a gift card, and redeem a gift card.
9
10use crate::{
11    config::Configuration,
12    http::client::HttpClient,
13    models::{
14        errors::ApiError, CreateGiftCardRequest, CreateGiftCardResponse,
15        LinkCustomerToGiftCardRequest, LinkCustomerToGiftCardResponse, ListGiftCardsParameters,
16        ListGiftCardsResponse, RetrieveGiftCardFromGANRequest, RetrieveGiftCardFromGANResponse,
17        RetrieveGiftCardFromNonceRequest, RetrieveGiftCardFromNonceResponse,
18        RetrieveGiftCardResponse, UnlinkCustomerFromGiftCardRequest,
19        UnlinkCustomerFromGiftCardResponse,
20    },
21};
22
23const DEFAULT_URI: &str = "/gift-cards";
24
25pub struct GiftCardsApi {
26    /// App config information
27    config: Configuration,
28    /// HTTP Client for requests to the Gift Cards API endpoints
29    client: HttpClient,
30}
31
32impl GiftCardsApi {
33    /// Instantiates a new `GiftCardsApi`
34    pub fn new(config: Configuration, client: HttpClient) -> Self {
35        Self { config, client }
36    }
37
38    /// Lists all gift cards.
39    ///
40    /// You can specify optional filters to retrieve a subset of the gift cards. Results are sorted
41    /// by created_at in ascending order.
42    pub async fn list_gift_cards(
43        &self,
44        params: &ListGiftCardsParameters,
45    ) -> Result<ListGiftCardsResponse, ApiError> {
46        let url = format!("{}{}", &self.url(), params.to_query_string());
47        let response = self.client.get(&url).await?;
48
49        response.deserialize().await
50    }
51
52    /// Creates a digital gift card or registers a physical (plastic) gift card.
53    ///
54    /// After the gift card is created, you must call
55    /// [CreateGiftCardActivity](https://developer.squareup.com/reference/square/giftcardactivities-api/create-gift-card-activity)
56    /// to activate the card with an initial balance before it can be used for payment.
57    pub async fn create_gift_card(
58        &self,
59        body: &CreateGiftCardRequest,
60    ) -> Result<CreateGiftCardResponse, ApiError> {
61        let response = self.client.post(&self.url(), body).await?;
62
63        response.deserialize().await
64    }
65
66    /// Retrieves a gift card using the gift card account number (GAN).
67    pub async fn retrieve_gift_card_from_gan(
68        &self,
69        body: &RetrieveGiftCardFromGANRequest,
70    ) -> Result<RetrieveGiftCardFromGANResponse, ApiError> {
71        let url = format!("{}/from-gan", &self.url());
72        let response = self.client.post(&url, body).await?;
73
74        response.deserialize().await
75    }
76
77    /// Retrieves a gift card using a secure payment token that represents the gift card.
78    pub async fn retrieve_gift_card_from_nonce(
79        &self,
80        body: &RetrieveGiftCardFromNonceRequest,
81    ) -> Result<RetrieveGiftCardFromNonceResponse, ApiError> {
82        let url = format!("{}/from-nonce", &self.url());
83        let response = self.client.post(&url, body).await?;
84
85        response.deserialize().await
86    }
87
88    /// Links a customer to a gift card, which is also referred to as adding a card on file.
89    ///
90    /// `gift_card_id`: The ID of the gift card to be linked.
91    pub async fn link_customer_to_gift_card(
92        &self,
93        gift_card_id: &str,
94        body: &LinkCustomerToGiftCardRequest,
95    ) -> Result<LinkCustomerToGiftCardResponse, ApiError> {
96        let url = format!("{}/{}/link-customer", &self.url(), gift_card_id);
97        let response = self.client.post(&url, body).await?;
98
99        response.deserialize().await
100    }
101
102    /// Unlinks a customer from a gift card, which is also referred to as removing a card on file.
103    ///
104    /// `gift_card_id`: The ID of the gift card to be linked.
105    pub async fn unlink_customer_from_gift_card(
106        &self,
107        gift_card_id: &str,
108        body: &UnlinkCustomerFromGiftCardRequest,
109    ) -> Result<UnlinkCustomerFromGiftCardResponse, ApiError> {
110        let url = format!("{}/{}/unlink-customer", &self.url(), gift_card_id);
111        let response = self.client.post(&url, body).await?;
112
113        response.deserialize().await
114    }
115
116    /// Retrieves a gift card using the gift card ID.
117    ///
118    /// `id`: The ID of the gift card to retrieve.
119    pub async fn retrieve_gift_card(&self, id: &str) -> Result<RetrieveGiftCardResponse, ApiError> {
120        let url = format!("{}/{}", &self.url(), id);
121        let response = self.client.get(&url).await?;
122
123        response.deserialize().await
124    }
125
126    /// Constructs the basic entity URL including domain and entity path. Any additional path
127    /// elements (e.g. path parameters) will need to be appended to this URL.
128    fn url(&self) -> String {
129        format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
130    }
131}
square_api_client/api/gift_cards_api.rs

square_api_client/api/
gift_cards_api.rs
