Square API Client

Square API Client provides a Rust wrapper on top of the Square web APIs.

Forked from https://github.com/cosm-public/rust-square-api-client-lib/tree/main on 1/4/2024.

Square API

Square APIs enable you to accept payments securely and integrate your app with Square’s first party product ecosystem. Build full-featured business apps for yourself or millions of Square sellers.

The Square API Reference is organized around core business workflows: taking payments, managing orders, syncing items and inventory with Square Point of Sale, creating customer records, managing business locations, and enabling Square sellers to use your app.

Usage

Setting up the client

The client is instantiated most simply with

use squareup::{config::Configuration, SquareClient};

// This will default to Sandbox, not Production!!
let client = SquareClient::try_new(Configuration::default()).unwrap();

For this to work, it's necessary to set an environment variable with the name of SQUARE_API_TOKEN and the value of your API Token string... otherwise, you'll get API errors when making live calls. You can also add your API Token to the Headers manually when configuring the client. Only do this for local scripts (if even then).

You also need to set the SQUARE_ENVIRONMENT environment variable to either SANDBOX or PRODUCTION. If a value is not set, the default is SANDBOX.

Other default values include the 2024-10-17 API version, a base URI of /v2, a timeout of 60 seconds and no HTTP Client retries.

The standard configuration for production is shown below:

    // Create square client config
    let config = Configuration {
        environment: Environment::Production, // OPTIONAL if you set the SQUARE_ENVIRONMENT env var
        http_client_config: HttpClientConfiguration::default(),
        base_uri: BaseUri::Default,
    };

The Square client can be customized a bit via the properties shown here:

use squareup::api::{CustomersApi, OrdersApi};
use squareup::config::BaseUri;
use squareup::config::{Configuration, Environment};
use squareup::http::client::HttpClientConfiguration;
use squareup::SquareClient;
use std::time::Duration;
use squareup::http::client::RetryConfiguration;
use squareup::http::Headers;

let mut headers = Headers::default();
headers.set_user_agent("Some User Agent String");
headers.insert("X_SOME_CUSTOM_HEADER", "custom_header_value");
// Not recommended to set auth header, only do this if you are running local scripts
headers.set_authorization("YOUR_API_TOKEN".to_string());

let config = Configuration {
    environment: Environment::Production,
    http_client_config: HttpClientConfiguration {
        timeout: 30,
        user_agent: String::from("Some User Agent String"), // will override what's in headers
        default_headers: headers,
        retry_configuration: RetryConfiguration {
            retries_count: 1,
            min_retry_interval: Duration::from_secs(1),
            max_retry_interval: Duration::from_secs(30 * 60),
            base: 3,
        },
    },
    base_uri: BaseUri::Default,
};

// Create square client
let square_client: SquareClient = SquareClient::try_new(config).unwrap();

Using the client

Once you have a SquareClient, inject the client into various APIs. This helps with safety by not allowing your app access to every API at once.

For example, to access the Customers API and Orders API, you would:

use squareup::api::{CustomersApi, OrdersApi};
use squareup::config::Configuration;
use squareup::SquareClient;

let square_client: SquareClient = SquareClient::try_new(Configuration::default()).unwrap();
let customers_api: CustomersApi = CustomersApi::new(square_client.clone());
let orders_api: OrdersApi = OrdersApi::new(square_client.clone());

Progress

The intent is to wrap all of the Square APIs in this crate. So far, it includes some of the more commonly required features.

Implemented so far

So far, we have the following APIs wrapped in the Rust Square API Client:

• Apple Pay
• Bookings
• Cards
• Catalog
• Checkout
• Customer Groups
• Customer Segments
• Customers
• Gift Card Activities
• Gift Cards
• Inventory
• Invoices
• Locations
• OAuth
• Orders
• Payments
• Refunds
• Subscriptions
• Team
• Webhook Subscriptions
• Webhooks

  • Bookings

  • Cards

  • Catalog

  • Checkout ("Online Checkout" in Square docs)

  • Customers

  • Gift Card Activities

  • Gift Cards

  • Inventory

  • Invoices

  • Locations

  • OAuth

  • Orders

  • Payments

  • Refunds

  • Subscriptions

  • Team

To be implemented

Future versions of this crate will implement the following APIs:

• Bank Accounts
• Booking Custom Attributes
• Cash Drawers
• Customer Custom Attributes
• Devices
• Disputes
• Events
• Labor
• Loyalty
• Location Custom Attributes
• Merchants
• Merchant Custom Attributes
• Mobile Authorization
• Order Custom Attributes
• Payouts
• Sites
• Snippets
• Terminal
• Vendors