Square Ruby SDK

https://github.com/square/square-ruby-sdk
Admin
The Square Ruby SDK provides convenient access to the Square API from Ruby applications, enabling...
Tokens:301,343
Snippets:2,138
Trust Score:9.4
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Create a subscription with client.subscriptions.create

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Enrolls a customer in a subscription. Provide a card on file to charge immediately, or omit it to send an invoice. The subscription starts immediately unless you include start_date. The example passes idempotency_key, location_id, plan_variation_id, customer_id, start_date, card_id, timezone, source, and phases.

```ruby
client.subscriptions.create(
  idempotency_key: '8193148c-9586-11e6-99f9-28cfe92138cf',
  location_id: 'S8GWD5R9QB376',
  plan_variation_id: '6JHXF3B2CW3YKHDV4XEM674H',
  customer_id: 'CHFGVKYY8RSV93M5KCYTG4PN0G',
  start_date: '2023-06-20',
  card_id: 'ccof:qy5x8hHGYsgLrp4Q4GB',
  timezone: 'America/Los_Angeles',
  source: {
    name: 'My Application'
  },
  phases: [{
    ordinal: 0,
    order_template_id: 'U2NaowWxzXwpsZU697x7ZHOAnCNZY'
  }]
);
```

--------------------------------

### Create bank account example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Example call to create_bank_account with all parameters. Returns a CreateBankAccountResponse object.

```ruby
client.bank_accounts.create_bank_account(
  idempotency_key: SecureRandom.uuid,
  source_id: "source_id_from_frontend",
  customer_id: "customer_id"
)
# => Square::Types::CreateBankAccountResponse
```

--------------------------------

### Authorize example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/08-oauth.md

Example call to redirect the user to the authorization page. Returns nil on success.

```ruby
client.o_auth.authorize   # returns nil on success
```

--------------------------------

### get example call

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Example call to retrieve a bank account by its Square-issued ID. The ID is passed as a keyword argument.

```ruby
client.bank_accounts.get(bank_account_id: "ba:12345678")
```

--------------------------------

### Install square.rb gem

Source: https://github.com/square/square-ruby-sdk/blob/master/README.md

Installs the Square Ruby SDK gem. Use this command to install the SDK globally or in your environment.

```bash
gem install square.rb
```

--------------------------------

### Retrieve token status example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/08-oauth.md

Example call to retrieve the status of an access token. Provide the access token as a parameter.

```ruby
client.o_auth.retrieve_token_status(access_token: "ACCESS_TOKEN")
```

--------------------------------

### Square Ruby SDK: List Payments and Create Bank Account

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/02-api-clients.md

Initializes the Square client with an API key, retrieves a page of payments using the cursor iterator, and creates a bank account with camelCase keys. The example assumes the 'square' gem is installed and the API key is valid.

```ruby
require "square"

client = Square::Client.new(token: "YOUR_API_KEY")

# A list endpoint returns a cursor iterator; pull one page via #pages
page = client.payments.list(cursor: nil).pages.next_page
puts page.payments.map(&:id)

# Create with camelCase keys is accepted too
client.bank_accounts.create_bank_account(
  account_number: "4532642645326322",
  country: "US",
  currency: "USD",
  account_type: "CHECKING",
  owner_name: "Ada Lovelace"
)
```

--------------------------------

### Get bank account by V1 ID example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Example call to get_by_v_1_id with a V1 bank account ID. Returns a GetBankAccountByV1IdResponse.

```ruby
client.bank_accounts.get_by_v_1_id(v_1_bank_account_id: "ba:12345678")
```

--------------------------------

### Bulk Swap Plan Usage Example

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Calls the bulk_swap_plan method on the subscriptions client to schedule a plan variation change for all active subscriptions under a given plan variation. The example passes new_plan_variation_id, old_plan_variation_id, and location_id as parameters.

```ruby
client.subscriptions.bulk_swap_plan(
  new_plan_variation_id: 'FQ7CDXXWSLUJRPM3GFJSJGZ7',
  old_plan_variation_id: '6JHXF3B2CW3YKHDV4XEM674H',
  location_id: 'S8GWD5R9QB376'
);
```

--------------------------------

### Obtain token example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/08-oauth.md

Example call to obtain an OAuth access token using the authorization_code grant type. Replace placeholders with actual credentials.

```ruby
client.o_auth.obtain_token(
  client_id: "CLIENT_ID",
  client_secret: "APPLICATION_SECRET",
  grant_type: "authorization_code",
  code: "AUTHORIZATION_CODE"
)
```

--------------------------------

### Manual paging for bank accounts list

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Manual paging example that gives equivalent control to the automatic iterator. It starts with a nil cursor, processes each page, and continues while a cursor is present, printing each bank account ID.

```ruby
response = client.bank_accounts.list(cursor: nil).pages.next_page
loop do
  break unless response.bank_accounts.any?

  response.bank_accounts.each { |ba| puts ba.id }
  break unless response.cursor

  response = client.bank_accounts.list(cursor: response.cursor).pages.next_page
end
```

--------------------------------

### GET v2/loyalty/programs

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Lists all loyalty programs for the seller.

```APIDOC
## GET v2/loyalty/programs

### Description
Lists all loyalty programs for the seller.

### Method
GET

### Endpoint
v2/loyalty/programs

### Response
#### Success Response (200)
- **ListLoyaltyProgramsResponse** - The response object containing the list of loyalty programs.

#### Response Example
```json
{
  "programs": []
}
```
```

--------------------------------

### Revoke token example

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/08-oauth.md

Example call to revoke an access token. Provide the client ID and the access token to revoke.

```ruby
client.o_auth.revoke_token(
  client_id: "CLIENT_ID",
  access_token: "ACCESS_TOKEN"
)
```

--------------------------------

### Start a transfer order with client.transfer_orders.start

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Changes a DRAFT transfer order to STARTED status, decrementing inventory at the source location. The order must be in DRAFT status and have all required fields populated. Once started, the order can no longer be deleted but can be canceled via CancelTransferOrder. Creates a transfer_order.updated webhook event.

```ruby
client.transfer_orders.start(
  transfer_order_id: 'transfer_order_id',
  idempotency_key: 'EXAMPLE_IDEMPOTENCY_KEY_789',
  version: 1753109537351
);
```

--------------------------------

### GET /v2/sites

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Lists all sites.

```APIDOC
## GET /v2/sites

### Description
Lists all sites.

### Method
GET

### Endpoint
`/v2/sites`

### Response
#### Success Response (200)
- **ListSitesResponse** - The list of sites response.

### Response Example
```json
{
  "sites": []
}
```

--------------------------------

### POST v2/transfer-orders/{transfer_order_id}/start

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Starts a transfer order.

```APIDOC
## POST v2/transfer-orders/{transfer_order_id}/start

### Description
Starts a transfer order.

### Method
POST

### Endpoint
v2/transfer-orders/{transfer_order_id}/start

### Parameters
#### Path Parameters
- **transfer_order_id** (string) - Required - The ID of the transfer order to start.

### Response
#### Success Response
- **StartTransferOrderResponse** - The response object for starting a transfer order.

```

--------------------------------

### GET v2/loyalty/programs/{program_id}/promotions

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Lists the promotions for a loyalty program.

```APIDOC
## GET v2/loyalty/programs/{program_id}/promotions

### Description
Lists the promotions for a loyalty program.

### Method
GET

### Endpoint
v2/loyalty/programs/{program_id}/promotions

### Parameters
#### Path Parameters
- **program_id** (string) - Required - The ID of the loyalty program.

### Response
#### Success Response (200)
- **ListLoyaltyPromotionsResponse** - The response object containing the list of promotions.

#### Response Example
```json
{
  "promotions": []
}
```
```

--------------------------------

### Use new and legacy SDKs together

Source: https://github.com/square/square-ruby-sdk/blob/master/README.md

Shows how to use the new SDK and the legacy SDK (exported as square_legacy) together in one file. Initializes both clients and demonstrates calling the new SDK for locations and the legacy SDK for payments.

```ruby
# Load both SDKs
require 'square'
require 'square_legacy'

# Initialize new SDK client
new_client = Square::Client.new(
  access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
)

# Initialize legacy SDK client
legacy_client = SquareLegacy::Client.new(
  bearer_auth_credentials: {
    access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
  }
)

# Use new SDK for newer features
locations = new_client.locations.get_locations.data.locations

# Use legacy SDK for specific legacy functionality
legacy_payment = legacy_client.payments_api.create_payment(
  body: {
    source_id: 'example_1234567890',
    idempotency_key: SecureRandom.uuid,
    amount_money: {
      amount: 100,
      currency: 'USD'
    }
  }
)
```

--------------------------------

### initialize(client:)

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/02-api-clients.md

Constructor for all domain client classes. Accepts a raw HTTP client instance and stores it for making requests.

```APIDOC
## initialize(client:)

### Description
Constructor for all domain client classes. Accepts a raw HTTP client instance and stores it for making requests.

### Method
N/A (constructor)

### Parameters
- **client** (Square::Internal::Http::RawClient) - Required - The raw HTTP client used to send requests.

### Request Example
```ruby
client = Square::Client.new
# ...

```

--------------------------------

### new (Client Constructor)

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/09-legacy-sdk.md

Initializes a SquareLegacy::Client instance with configurable connection, retry, authentication, and headers.

```APIDOC
## new (Client Constructor)

### Description
Initializes a `SquareLegacy::Client` instance for interacting with the legacy Square SDK, allowing configuration of connection settings, retries, authentication, and request headers.

### Method
`new`

### Parameters
- `connection` (Object) - Optional - Prebuilt connection (passed to `Configuration`). Default: `nil`.
- `adapter` (Symbol) - Optional - HTTP adapter identifier. Default: `:net_http_persistent`.
- `timeout` (Integer) - Optional - Request timeout in seconds. Default: `60`.
- `max_retries` (Integer) - Optional - Retry count. Default: `0`.
- `retry_interval` (Integer) - Optional - Seconds between retries. Default: `1`.
- `backoff_factor` (Integer) - Optional - Backoff multiplier per retry. Default: `2`.
- `retry_statuses` (Array[Integer]) - Optional - Status codes that trigger retry. Default: `[408, 413, 429, 500, 502, 503, 504, 521, 522, 524]`.
- `retry_methods` (Array[Symbol]) - Optional - HTTP methods that are retried. Default: `[:get, :put]`.
- `http_callback` (Object) - Optional - Callback hook for HTTP events. Default: `nil`.
- `environment` (String) - Optional - API environment name. Default: `'production'`.
- `custom_url` (String) - Optional - Base URL for requests. Default: `'https://connect.squareup.com'`.
- `access_token` (String) - Optional - Personal access token. Default: `nil`.
- `bearer_auth_credentials` (Hash) - Optional - Hash with `access_token:` for OAuth2 bearer credentials. Default: `nil`.
- `square_version` (String) - Optional - Square Connect API version used in User-Agent. Default: `'2025-06-18'`.
- `user_agent_detail` (String) - Optional - Extra User-Agent detail. Default: `''`.
- `additional_headers` (Hash) - Optional - Extra headers added to every request. Default: `{}`.
- `config` (SquareLegacy::Configuration) - Optional - When provided, used instead of building a new `Configuration`. Default: `nil`.

### Request Example
```ruby
legacy_client = SquareLegacy::Client.new(
  bearer_auth_credentials: { access_token: 'YOUR_SQUARE_ACCESS_TOKEN' }
)
```

### Response
#### Reader Methods
- `config` - Returns the configuration object.
- `auth_managers` - Returns the auth managers.
- `sdk_version` - Returns `'43.0.1.20250716'`.
- `square_version` - Returns the Square API version.
- `user_agent_detail` - Returns the user agent detail string.

```

--------------------------------

### SquareLegacy::Configuration#initialize

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/09-legacy-sdk.md

Initializes the Square Legacy SDK configuration with connection, retry, authentication, and version settings.

```APIDOC
## `SquareLegacy::Configuration`

### Description
Initializes the Square Legacy SDK configuration with connection, retry, authentication, and version settings.

### Method
`initialize`

### Parameters
- `connection` (Object) - Optional - Custom Faraday connection.
- `adapter` (Symbol) - Optional - HTTP adapter to use (default: `:net_http_persistent`).
- `timeout` (Integer) - Optional - Timeout in seconds (default: `60`).
- `max_retries` (Integer) - Optional - Maximum number of retries (default: `0`).
- `retry_interval` (Integer) - Optional - Base retry interval in seconds (default: `1`).
- `backoff_factor` (Integer) - Optional - Backoff multiplier (default: `2`).
- `retry_statuses` (Array) - Optional - HTTP statuses to retry on (default: `[408, 413, 429, 500, 502, 503, 504, 521, 522, 524]`).
- `retry_methods` (Array) - Optional - HTTP methods to retry (default: `[:get, :put]`).
- `http_callback` (Object) - Optional - HTTP callback handler.
- `environment` (String) - Optional - Environment name (default: `'production'`).
- `custom_url` (String) - Optional - Base URL for API requests (default: `'https://connect.squareup.com'`).
- `access_token` (String) - Optional - OAuth access token.
- `bearer_auth_credentials` (Object) - Optional - Pre-configured bearer credentials.
- `square_version` (String) - Optional - Square API version (default: `'2025-06-18'`).
- `user_agent_detail` (String) - Optional - Additional user agent detail.
- `additional_headers` (Hash) - Optional - Extra headers to include in requests.

### Readers
- `access_token` - Returns the access token.
- `environment` - Returns the environment.
- `custom_url` - Returns the custom URL.
- `bearer_auth_credentials` - Returns the bearer credentials.
- `square_version` - Returns the Square version.
- `user_agent_detail` - Returns the user agent detail.
- `additional_headers` - Returns a clone of the additional headers.

### Example
```ruby
config = SquareLegacy::Configuration.new(
  access_token: 'YOUR_ACCESS_TOKEN',
  environment: 'production',
  square_version: '2025-06-18'
)
```

```

--------------------------------

### Legacy SDK client initialization (before)

Source: https://github.com/square/square-ruby-sdk/blob/master/README.md

Old-style client initialization for the legacy SDK. This is the before state in the migration steps.

```ruby
client = Square::Client.new(access_token: 'token')
```

--------------------------------

### Legacy SDK client initialization (after)

Source: https://github.com/square/square-ruby-sdk/blob/master/README.md

New-style client initialization for the legacy SDK. This is the after state in the migration steps.

```ruby
client = SquareLegacy::Client.new(
  bearer_auth_credentials: { access_token: 'token' }
)
```

--------------------------------

### disable_bank_account example call

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Example call to disable a bank account by its Square-issued ID. The ID is passed as a keyword argument.

```ruby
client.bank_accounts.disable_bank_account(bank_account_id: "ba:12345678")
```

--------------------------------

### Initialize Square::Client with base_url and token

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/01-client.md

Constructor for the root client. Reads base_url and token once at construction; they cannot be changed later. Falls back to Square::Environment::PRODUCTION and ENV.fetch("SQUARE_TOKEN", nil) when omitted.

```ruby
def initialize(base_url: nil, token: ENV.fetch("SQUARE_TOKEN", nil))
  @raw_client = Square::Internal::Http::RawClient.new(
    base_url: base_url || Square::Environment::PRODUCTION,
    headers: {
      "User-Agent" => "square.rb/47.0.0.20260916",
      "X-Fern-Language" => "Ruby",
      Authorization: "Bearer #{token}"
    }
  )
end
```

--------------------------------

### Basic usage of load_and_wait

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/07-reporting.md

Shows how to require the helper, create a client, and call load_and_wait with a reporting query. The response data is iterated and printed.

```ruby
require "square"
require "square/reporting_helper"

client = Square::Client.new(token: ENV.fetch("SQUARE_TOKEN"))

metadata = client.reporting.get_metadata

response = client.reporting.load_and_wait(
  query: {
    measures: ["orders.count"],
    time_dimensions: [{ dimension: "orders.created_at", granularity: "day" }]
  }
)
response.data.each { |row| puts row }
```

--------------------------------

### Get a location with client.locations.get()

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves details of a single location by ID. Use 'main' as the location_id to get the main location.

```ruby
client.locations.get(location_id: 'location_id');
```

--------------------------------

### Basic initialization with Square::Client

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/01-client.md

Initializes the Square client with a token from the SQUARE_TOKEN environment variable and fetches the first location name.

```ruby
require "square"

client = Square::Client.new(
  token: ENV.fetch("SQUARE_TOKEN")
)

locations = client.locations.get_locations.data.locations
puts locations.first.name
```

--------------------------------

### Create an order with client.orders.create

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a new order with line items, taxes, discounts, and an idempotency key. The order can include catalog items, modifiers, and various discount types. Use this to create an order for purchase.

```ruby
client.orders.create(
  order: {
    location_id: '057P5VYJ4A5X1',
    reference_id: 'my-order-001',
    line_items: [{
      name: 'New York Strip Steak',
      quantity: '1',
      base_price_money: {
        amount: 1599,
        currency: 'USD'
      }
    }, {
      quantity: '2',
      catalog_object_id: 'BEMYCSMIJL46OCDV4KYIKXIB',
      modifiers: [{
        catalog_object_id: 'CHQX7Y4KY6N5KINJKZCFURPZ'
      }],
      applied_discounts: [{
        discount_uid: 'one-dollar-off'
      }]
    }],
    taxes: [{
      uid: 'state-sales-tax',
      name: 'State Sales Tax',
      percentage: '9',
      scope: 'ORDER'
    }],
    discounts: [{
      uid: 'labor-day-sale',
      name: 'Labor Day Sale',
      percentage: '5',
      scope: 'ORDER'
    }, {
      uid: 'membership-discount',
      catalog_object_id: 'DB7L55ZH2BGWI4H23ULIWOQ7',
      scope: 'ORDER'
    }, {
      uid: 'one-dollar-off',
      name: 'Sale - $1.00 off',
      amount_money: {
        amount: 100,
        currency: 'USD'
      },
      scope: 'LINE_ITEM'
    }]
  },
  idempotency_key: '8193148c-9586-11e6-99f9-28cfe92138cf'
);
```

--------------------------------

### Initialize Reporting Client and Define Methods

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/07-reporting.md

Shows the constructor and method signatures for Square::Reporting::Client. The client is initialized with a client object, and both get_metadata and load accept request options and additional parameters.

```ruby
# lib/square/reporting/client.rb
def initialize(client:)
  @client = client
end

def get_metadata(request_options: {}, **params)
def load(request_options: {}, **params)

```

--------------------------------

### get method signature

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/03-bank-accounts.md

Method signature for the get operation. It accepts a bank_account_id parameter and optional request options. Returns a Square::Types::GetBankAccountResponse.

```ruby
def get(request_options: {}, **params)
```

--------------------------------

### Get merchant by ID using client.merchants.get

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves a merchant by its ID. The merchant_id can be 'me' to get the currently accessible merchant. Returns a Square::Types::GetMerchantResponse.

```ruby
client.merchants.get(merchant_id: 'merchant_id');
```

--------------------------------

### Create loyalty promotion with client.loyalty.programs.promotions.create

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a loyalty promotion for a program, enabling buyers to earn extra points. Sets the promotion to ACTIVE or SCHEDULED based on available_time, with a maximum of 10 ACTIVE or SCHEDULED promotions per program. Requires program_id, loyalty_promotion, and idempotency_key parameters.

```ruby
client.loyalty.programs.promotions.create(
  program_id: 'program_id',
  loyalty_promotion: {
    name: 'Tuesday Happy Hour Promo',
    incentive: {
      type: 'POINTS_MULTIPLIER',
      points_multiplier_data: {
        multiplier: '3.0'
      }
    },
    available_time: {
      time_periods: ['BEGIN:VEVENT
      DTSTART:20220816T160000
      DURATION:PT2H
      RRULE:FREQ=WEEKLY;BYDAY=TU
      END:VEVENT']
    },
    trigger_limit: {
      times: 1,
      interval: 'DAY'
    },
    minimum_spend_amount_money: {
      amount: 2000,
      currency: 'USD'
    },
    qualifying_category_ids: ['XTQPYLR3IIU9C44VRCB3XD12']
  },
  idempotency_key: 'ec78c477-b1c3-4899-a209-a4e71337c996'
);
```

--------------------------------

### Get customer by ID

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves a single customer's details using the 'get' endpoint. The 'customer_id' parameter is required and specifies the ID of the customer to retrieve.

```ruby
client.customers.get(customer_id: 'customer_id');
```

--------------------------------

### Create customer with client.customers.create()

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a new customer for a business. You must provide at least one of the following values in the request: given_name, family_name, company_name, email_address, or phone_number.

```ruby
client.customers.create(
  given_name: 'Amelia',
  family_name: 'Earhart',
  email_address: 'Amelia.Earhart@example.com',
  address: {
    address_line_1: '500 Electric Ave',
    address_line_2: 'Suite 600',
    locality: 'New York',
    administrative_district_level_1: 'NY',
    postal_code: '10003',
    country: 'US'
  },
  phone_number: '+1-212-555-4240',
  reference_id: 'YOUR_REFERENCE_ID',
  note: 'a customer'
);
```

--------------------------------

### List payments with all parameters

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves a list of payments. Results are eventually consistent and may take seconds to appear. The maximum results per page is 100. The example shows all available parameters, including `begin_time`, `end_time`, `sort_order`, `cursor`, `location_id`, `total`, `last_4`, `card_brand`, `limit`, `is_offline_payment`, and various timestamps.

```ruby
client.payments.list(
  begin_time: 'begin_time',
  end_time: 'end_time',
  sort_order: 'sort_order',
  cursor: 'cursor',
  location_id: 'location_id',
  total: 1000000,
  last_4: 'last_4',
  card_brand: 'card_brand',
  limit: 1,
  is_offline_payment: true,
  offline_begin_time: 'offline_begin_time',
  offline_end_time: 'offline_end_time',
  updated_at_begin_time: 'updated_at_begin_time',
  updated_at_end_time: 'updated_at_end_time',
  sort_field: 'CREATED_AT'
);
```

--------------------------------

### CursorPageIterator initializer

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/04-pagination.md

Initializes a CursorPageIterator with the starting cursor, the response field containing the next cursor, and a block that fetches each page. The initial_cursor can be nil to start from the first page.

```ruby
def initialize(initial_cursor:, cursor_field:, &block)

```

--------------------------------

### get

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves a loyalty account.

```APIDOC
## get

### Description
Retrieves a loyalty account.

### Method
GET

### Endpoint
/loyalty/accounts/{account_id}

### Parameters
#### Path Parameters
- **account_id** (String) - Required - The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve.

#### Request Options
- **request_options** (Square::Loyalty::Accounts::RequestOptions) - Optional - Request options.

### Request Example
```ruby
client.loyalty.accounts.get(account_id: 'account_id');
```

### Response
#### Success Response (200)
- **response** (Square::Types::GetLoyaltyAccountResponse) - The response from the get operation.

#### Response Example
```json
{
  "loyalty_account": {
    "id": "id",
    "program_id": "program_id",
    "balance": 0,
    "lifetime_points": 0,
    "mapping": {
      "phone_number": "phone_number"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}
```
```

--------------------------------

### GET v2/merchants

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Lists all merchants.

```APIDOC
## GET v2/merchants

### Description
Lists all merchants.

### Method
GET

### Endpoint
v2/merchants

### Response
#### Success Response (200)
- **ListMerchantsResponse** - The response object containing the list of merchants.

#### Response Example
```json
{
  "merchants": []
}
```
```

--------------------------------

### List loyalty promotions with client.loyalty.programs.promotions.list

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Lists loyalty promotions for a given program, sorted by created_at in descending order. Accepts optional status, cursor, and limit parameters for filtering and pagination. The limit parameter has a minimum of 1, maximum of 30, and defaults to 30.

```ruby
client.loyalty.programs.promotions.list(
  program_id: 'program_id',
  status: 'ACTIVE',
  cursor: 'cursor',
  limit: 1
);
```

--------------------------------

### List bookings with client.bookings.list

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Use this snippet to retrieve a collection of bookings. All parameters are optional; if not set, bookings for all customers, team members, and locations are retrieved. The start_at_min defaults to the current time, and start_at_max defaults to 31 days after start_at_min.

```ruby
client.bookings.list(
  limit: 1,
  cursor: 'cursor',
  customer_id: 'customer_id',
  team_member_id: 'team_member_id',
  location_id: 'location_id',
  start_at_min: 'start_at_min',
  start_at_max: 'start_at_max'
);
```

--------------------------------

### GET oauth2/authorize

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Authorizes an OAuth request.

```APIDOC
## GET oauth2/authorize

### Description
Authorizes an OAuth request.

### Method
GET

### Endpoint
oauth2/authorize

### Response
#### Success Response (200)
- No response body specified.

#### Response Example
```json
{}
```
```

--------------------------------

### create

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a Terminal action request and sends it to the specified device.

```APIDOC
## create

### Description
Creates a Terminal action request and sends it to the specified device.

### Method
POST

### Endpoint
/terminal/actions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **idempotency_key** (String) - Required - A unique string that identifies this `CreateAction` request. Keys can be any valid string but must be unique for every `CreateAction` request.
- **action** (Square::Types::TerminalAction) - Required - The Action to create.
- **request_options** (Square::Terminal::Actions::RequestOptions) - Optional - Additional request options.

### Request Example
```ruby
client.terminal.actions.create(
  idempotency_key: 'thahn-70e75c10-47f7-4ab6-88cc-aaa4076d065e',
  action: {
    device_id: '{{DEVICE_ID}}',
    deadline_duration: 'PT5M',
    type: 'SAVE_CARD',
    save_card_options: {
      customer_id: '{{CUSTOMER_ID}}',
      reference_id: 'user-id-1'
    }
  }
);
```

### Response
#### Success Response (200)
- **Square::Types::CreateTerminalActionResponse** - The response object containing the created terminal action.

#### Response Example
```json
{
  "action": {
    "id": "term_action_id",
    "status": "IN_PROGRESS"
  }
}
```
```

--------------------------------

### GET v2/webhooks/subscriptions

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Lists webhook subscriptions.

```APIDOC
## GET v2/webhooks/subscriptions

### Description
Lists webhook subscriptions.

### Method
GET

### Endpoint
v2/webhooks/subscriptions

### Response
#### Success Response
- **ListWebhookSubscriptionsResponse** - The response object for listing webhook subscriptions.

```

--------------------------------

### batch_upsert usage example

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates or updates order custom attributes in bulk. The example passes a map of upsert requests, each with a custom attribute key, version, and order_id. The endpoint accepts 1 to 25 individual upsert requests.

```ruby
client.orders.custom_attributes.batch_upsert(values: {
  'cover-count' => {
    custom_attribute: {
      key: 'cover-count',
      version: 2
    },
    order_id: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F'
  },
  'table-number' => {
    custom_attribute: {
      key: 'table-number',
      version: 4
    },
    order_id: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F'
  }
});
```

--------------------------------

### POST v2/loyalty/programs/{program_id}/promotions

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Creates a promotion for a loyalty program.

```APIDOC
## POST v2/loyalty/programs/{program_id}/promotions

### Description
Creates a promotion for a loyalty program.

### Method
POST

### Endpoint
v2/loyalty/programs/{program_id}/promotions

### Parameters
#### Path Parameters
- **program_id** (string) - Required - The ID of the loyalty program.

### Response
#### Success Response (200)
- **CreateLoyaltyPromotionResponse** - The response object containing the created promotion.

#### Response Example
```json
{
  "promotion": {}
}
```
```

--------------------------------

### batch_delete usage example

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Deletes order custom attributes in bulk. The example passes a map of delete requests, each with a unique key, order_id, and custom attribute key. The endpoint accepts 1 to 25 individual delete requests.

```ruby
client.orders.custom_attributes.batch_delete(values: {
  'cover-count' => {
    key: 'cover-count',
    order_id: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F'
  },
  'table-number' => {
    key: 'table-number',
    order_id: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F'
  }
});
```

--------------------------------

### Create a location with client.locations.create()

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a new location with a required unique name and optional fields like address and description. The location persists forever and is visible to the seller for management.

```ruby
client.locations.create(location: {
  name: 'Midtown',
  address: {
    address_line_1: '1234 Peachtree St. NE',
    locality: 'Atlanta',
    administrative_district_level_1: 'GA',
    postal_code: '30309'
  },
  description: 'Midtown Atlanta store'
});
```

--------------------------------

### get(id)

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Retrieves a payment link by its ID.

```APIDOC
## get(id)

### Description
Retrieves a payment link.

### Method
GET

### Endpoint
/payment-links/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The ID of link to retrieve.

### Request Example
```ruby
client.checkout.payment_links.get(id: 'id');
```

### Response
#### Success Response (200)
Returns a `Square::Types::GetPaymentLinkResponse` object.

#### Response Example
```json
{
  "payment_link": {
    "id": "string",
    "url": "string"
  }
}
```
```

--------------------------------

### Create Card - client.cards.create()

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Adds a card on file to an existing merchant. Requires idempotency_key, source_id, and card details. The card object includes cardholder_name, billing_address, customer_id, and reference_id.

```ruby
client.cards.create(
  idempotency_key: '4935a656-a929-4792-b97c-8848be85c27c',
  source_id: 'cnon:uIbfJXhXETSP197M3GB',
  card: {
    cardholder_name: 'Amelia Earhart',
    billing_address: {
      address_line_1: '500 Electric Ave',
      address_line_2: 'Suite 600',
      locality: 'New York',
      administrative_district_level_1: 'NY',
      postal_code: '10003',
      country: 'US'
    },
    customer_id: 'VDKXEEKPJN48Q3BGGFAK05P8',
    reference_id: 'user-id-1'
  }
);
```

--------------------------------

### GET v2/refunds

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Retrieves a list of refunds for a merchant.

```APIDOC
## GET v2/refunds

### Description
Retrieves a list of refunds for a merchant.

### Method
GET

### Endpoint
v2/refunds

### Response
#### Success Response (200)
- **ListPaymentRefundsResponse** - The response object containing a list of refunds.

#### Response Example
```json
{
  "refunds": [
    {
      "id": "refund_id",
      "status": "COMPLETED"
    }
  ]
}
```
```

--------------------------------

### GET v2/payouts

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Retrieves a list of payouts for a merchant.

```APIDOC
## GET v2/payouts

### Description
Retrieves a list of payouts for a merchant.

### Method
GET

### Endpoint
v2/payouts

### Response
#### Success Response (200)
- **ListPayoutsResponse** - The response object containing a list of payouts.

#### Response Example
```json
{
  "payouts": [
    {
      "id": "payout_id",
      "status": "PAID"
    }
  ]
}
```
```

--------------------------------

### list()

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Returns a list of loyalty programs in the seller's account. This method is replaced by RetrieveLoyaltyProgram when used with the keyword 'main'.

```APIDOC
## list()

### Description
Returns a list of loyalty programs in the seller's account. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).

Replaced with [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) when used with the keyword `main`.

### Method
GET

### Endpoint
/loyalty/programs

### Parameters
#### Query Parameters
- **request_options** (Square::Loyalty::Programs::RequestOptions) - Optional - Request options for the API call.

### Request Example
```ruby
client.loyalty.programs.list();
```

### Response
#### Success Response (200)
- **programs** (Array) - The list of loyalty programs.

#### Response Example
```json
{
  "programs": [
    {
      "id": "program_id",
      "type": "LOYALTY_PROGRAM"
    }
  ]
}
```
```

--------------------------------

### SquareLegacy::Configuration initialize

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/api-reference/09-legacy-sdk.md

Constructor signature for SquareLegacy::Configuration, which extends CoreLibrary::HttpClientConfiguration. Defaults include timeout 60, max_retries 0, retry_statuses list, environment 'production', custom_url 'https://connect.squareup.com', and square_version '2025-06-18'. Readers include access_token, environment, custom_url, bearer_auth_credentials, square_version, user_agent_detail, and additional_headers (returns a clone).

```ruby
def initialize(
  connection: nil, adapter: :net_http_persistent, timeout: 60,
  max_retries: 0, retry_interval: 1, backoff_factor: 2,
  retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
  retry_methods: %i[get put], http_callback: nil, environment: 'production',
  custom_url: 'https://connect.squareup.com', access_token: nil,
  bearer_auth_credentials: nil, square_version: '2025-06-18',
  user_agent_detail: '', additional_headers: {}
)
```

--------------------------------

### GET v2/webhooks/event-types

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Lists webhook event types.

```APIDOC
## GET v2/webhooks/event-types

### Description
Lists webhook event types.

### Method
GET

### Endpoint
v2/webhooks/event-types

### Response
#### Success Response
- **ListWebhookEventTypesResponse** - The response object for listing webhook event types.

```

--------------------------------

### create

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a loyalty account. To create a loyalty account, you must provide the program_id and a mapping with the phone_number of the buyer.

```APIDOC
## create

### Description
Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.

### Method
POST

### Endpoint
/loyalty/accounts

### Parameters
#### Request Body
- **loyalty_account** (Square::Types::LoyaltyAccount) - Required - The loyalty account to create.
- **idempotency_key** (String) - Required - A unique string that identifies this `CreateLoyaltyAccount` request. Keys can be any valid string, but must be unique for every request.
- **request_options** (Square::Loyalty::Accounts::RequestOptions) - Optional - Request options.

### Request Example
```ruby
client.loyalty.accounts.create(
  loyalty_account: {
    program_id: 'd619f755-2d17-41f3-990d-c04ecedd64dd',
    mapping: {
      phone_number: '+14155551234'
    }
  },
  idempotency_key: 'ec78c477-b1c3-4899-a209-a4e71337c996'
);
```

### Response
#### Success Response (200)
- **response** (Square::Types::CreateLoyaltyAccountResponse) - The response from the create operation.

#### Response Example
```json
{
  "loyalty_account": {
    "id": "id",
    "program_id": "program_id",
    "balance": 0,
    "lifetime_points": 0,
    "mapping": {
      "phone_number": "phone_number"
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}
```
```

--------------------------------

### GET v2/vendors/{vendor_id}

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Retrieves a vendor by its ID.

```APIDOC
## GET v2/vendors/{vendor_id}

### Description
Retrieves a vendor by its ID.

### Method
GET

### Endpoint
v2/vendors/{vendor_id}

### Parameters
#### Path Parameters
- **vendor_id** (string) - Required - The ID of the vendor to retrieve.

### Response
#### Success Response
- **GetVendorResponse** - The response object for retrieving a vendor.

```

--------------------------------

### GET /v2/team-members/jobs

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Lists all team member jobs.

```APIDOC
## GET /v2/team-members/jobs

### Description
Lists all team member jobs.

### Method
GET

### Endpoint
`/v2/team-members/jobs`

### Response
#### Success Response (200)
- **ListJobsResponse** - The list jobs response.

### Response Example
```json
{
  "jobs": []
}
```

--------------------------------

### Create bank account with client.bank_accounts.create_bank_account

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Stores a bank account on file for a Square account. Requires an idempotency key, a source ID (payment token from WebSDK), and optionally a customer ID.

```ruby
client.bank_accounts.create_bank_account(
  idempotency_key: '4e43559a-f0fd-47d3-9da2-7ea1f97d94be',
  source_id: 'bnon:CA4SEHsQwr0rx6DbWLD5BQaqMnoYAQ',
  customer_id: 'HM3B2D5JKGJ69359BTEHXM2V8M'
);
```

--------------------------------

### GET /v2/subscriptions/{subscription_id}

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Retrieves a specific subscription.

```APIDOC
## GET /v2/subscriptions/{subscription_id}

### Description
Retrieves a specific subscription.

### Method
GET

### Endpoint
`/v2/subscriptions/{subscription_id}`

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription.

### Response
#### Success Response (200)
- **GetSubscriptionResponse** - The subscription response.

### Response Example
```json
{
  "subscription": {}
}
```

--------------------------------

### GET /reporting/v1/meta

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-3.md

Retrieves metadata for the reporting API.

```APIDOC
## GET /reporting/v1/meta

### Description
Retrieves metadata for the reporting API.

### Method
GET

### Endpoint
`/reporting/v1/meta`

### Response
#### Success Response (200)
- **MetadataResponse** - The metadata response object.

### Response Example
```json
{
  "metadata": {}
}
```
```

--------------------------------

### GET v2/orders/custom-attribute-definitions

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Lists the custom attribute definitions for orders.

```APIDOC
## GET v2/orders/custom-attribute-definitions

### Description
Lists the custom attribute definitions for orders.

### Method
GET

### Endpoint
v2/orders/custom-attribute-definitions

### Response
#### Success Response (200)
- **ListOrderCustomAttributeDefinitionsResponse** - The response object containing the list of custom attribute definitions.

#### Response Example
```json
{
  "custom_attribute_definitions": []
}
```
```

--------------------------------

### client.bookings.create(request)

Source: https://github.com/square/square-ruby-sdk/blob/master/reference.md

Creates a booking with the provided details. Requires specific booking fields and appropriate OAuth scopes.

```APIDOC
## client.bookings.create(request)

### Description
Creates a booking. The required input must include the following: `Booking.location_id`, `Booking.start_at`, `Booking.AppointmentSegment.team_member_id`, `Booking.AppointmentSegment.service_variation_id`, `Booking.AppointmentSegment.service_variation_version`. To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope. To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope. For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus* or *Appointments Premium*.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **idempotency_key** (String) - Optional - A unique key to make this request an idempotent operation.
- **booking** (Square::Types::Booking) - Required - The details of the booking to be created.

### Request Example
```ruby
client.bookings.create(booking: {});
```

### Response
#### Success Response (200)
- **response** (Square::Types::CreateBookingResponse) - The response from the API call.

#### Response Example
```json
{}
```
```

--------------------------------

### GET v2/orders/{order_id}

Source: https://github.com/square/square-ruby-sdk/blob/master/_autodocs/endpoints-2.md

Retrieves a specific order by its ID.

```APIDOC
## GET v2/orders/{order_id}

### Description
Retrieves a specific order by its ID.

### Method
GET

### Endpoint
v2/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The ID of the order to retrieve.

### Response
#### Success Response (200)
- **GetOrderResponse** - The response object containing the order details.

#### Response Example
```json
{
  "order": {}
}
```
```
Tokens:
Raw