Square Java SDK

https://github.com/square/square-java-sdk
Admin
Square Java SDK provides convenient access to Square APIs from Java applications for payments,...
Tokens:221,522
Snippets:1,380
Trust Score:9.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Client Instantiation

Source: https://context7.com/square/square-java-sdk/llms.txt

Demonstrates how to instantiate the synchronous SquareClient using various configuration options, including environment selection, explicit token, timeouts, retry limits, custom HTTP clients, and headers.

```APIDOC
## Client Instantiation — `SquareClient.builder()`

The entry point for all API calls; credentials can be supplied explicitly or read from the `SQUARE_TOKEN` environment variable. The builder exposes environment selection, custom base URLs, timeout, retry limits, custom HTTP client, and custom headers.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;
import com.squareup.square.core.RequestOptions;
import okhttp3.OkHttpClient;

// Minimal — token from env var SQUARE_TOKEN
SquareClient client = SquareClient.builder().build();

// Explicit token + sandbox environment
SquareClient client = SquareClient.builder()
    .token("YOUR_SQUARE_TOKEN")
    .environment(Environment.SANDBOX)
    .build();

// Full customisation
OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
    .build();

SquareClient client = SquareClient.builder()
    .token("YOUR_SQUARE_TOKEN")
    .environment(Environment.PRODUCTION)
    .timeout(60)           // seconds
    .maxRetries(3)
    .httpClient(httpClient)
    .addHeader("X-App-Version", "2.0.0")
    .build();
```
```

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

### Get Team Member

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

Retrieves a specific TeamMember object using their unique ID. Includes a link to troubleshooting guides.

```APIDOC
## Get Team Member

### Description
Retrieves a `TeamMember` object for the given `TeamMember.id`. Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrieve-a-team-member).

### Method
GET

### Endpoint
/team_members/{team_member_id}

### Parameters
#### Path Parameters
- **teamMemberId** (String) - Required - The ID of the team member to retrieve.

### Request Example
```java
client.teamMembers().get(
    GetTeamMembersRequest
        .builder()
        .teamMemberId("team_member_id")
        .build()
);
```

### Response
#### Success Response (200)
- **team_member** (TeamMember) - The retrieved TeamMember object.

#### Response Example
{
  "team_member": {
    "id": "0G5P3VGACMMQZ",
    "given_name": "Test",
    "family_name": "User",
    "email_address": "testuser@example.com",
    "phone_number": "+14155551234",
    "status": "ACTIVE",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}
```

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

### Start Transfer Order in Java

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

Use this to change a DRAFT transfer order to STARTED status. This action decrements inventory at the source location and marks it as in-transit. The order must be in DRAFT status and cannot be deleted after being started. An idempotency key is required for this operation.

```java
client.transferOrders().start(
    StartTransferOrderRequest
        .builder()
        .transferOrderId("transfer_order_id")
        .idempotencyKey("EXAMPLE_IDEMPOTENCY_KEY_789")
        .version(1753109537351L)
        .build()
);
```

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

### Instantiate New and Legacy Square SDK Clients

Source: https://context7.com/square/square-java-sdk/llms.txt

Demonstrates how to instantiate both the new Square SDK client and the legacy Square SDK client. Use the new client for new code paths and the legacy client for existing ones during the migration process.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;

// New SDK client
SquareClient newClient = SquareClient.builder()
    .environment(Environment.PRODUCTION)
    .token("YOUR_TOKEN")
    .build();

// Legacy SDK client (same token, old builder pattern)
com.squareup.square.legacy.SquareClient legacyClient =
    new com.squareup.square.legacy.SquareClient.Builder()
        .environment(com.squareup.square.legacy.Environment.PRODUCTION)
        .accessToken("YOUR_TOKEN")
        .build();

// Use new client for new code paths, legacy client for existing ones
newClient.payments().list().streamItems().forEach(p -> System.out.println(p.getId()));
legacyClient.getPaymentsApi().listPayments(null, null, null, null, null, null, null, null, null);
```

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

### Create, Pay, and Search Orders

Source: https://context7.com/square/square-java-sdk/llms.txt

Provides examples for creating an order with line items, paying for an order using payment IDs, and searching for orders based on location and status. Ensure `com.squareup.square.types.*` and `java.util.List` are imported.

```java
import com.squareup.square.types.*;
import java.util.List;

// Create an order
CreateOrderResponse orderResp = client.orders().create(
    CreateOrderRequest.builder()
        .idempotencyKey(java.util.UUID.randomUUID().toString())
        .order(Order.builder()
            .locationId("L88917AVBK2S5")
            .lineItems(List.of(
                OrderLineItem.builder()
                    .name("Latte")
                    .quantity("2")
                    .basePriceMoney(Money.builder().amount(450L).currency(Currency.USD).build())
                    .build()
            ))
            .build())
        .build()
);
String orderId = orderResp.getOrder().map(Order::getId).orElseThrow();

// Pay for the order
client.orders().pay(
    PayOrderRequest.builder()
        .orderId(orderId)
        .idempotencyKey(java.util.UUID.randomUUID().toString())
        .paymentIds(List.of("PAYMENT_ID"))
        .build()
);

// Search orders
SearchOrdersResponse search = client.orders().search(
    SearchOrdersRequest.builder()
        .locationIds(List.of("L88917AVBK2S5"))
        .query(SearchOrdersQuery.builder()
            .filter(SearchOrdersFilter.builder()
                .stateFilter(SearchOrdersStateFilter.builder()
                    .states(List.of(OrderState.COMPLETED))
                    .build())
                .build())
            .build())
        .build()
);
search.getOrders().ifPresent(orders -> orders.forEach(o -> System.out.println(o.getId())));
```

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

### Update a Workweek Configuration

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

Updates an existing WorkweekConfig object. Requires the UUID of the WorkweekConfig to be updated and a WorkweekConfig object containing the new details, such as start of the week and start of the day.

```java
client.labor().workweekConfigs().get(
    UpdateWorkweekConfigRequest
        .builder()
        .id("id")
        .workweekConfig(
            WorkweekConfig
                .builder()
                .startOfWeek(Weekday.MON)
                .startOfDayLocalTime("10:00")
                .version(10)
                .build()
        )
        .build()
);
```

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

### Create an Order with Line Items, Taxes, and Discounts

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

Use this snippet to create a new order with detailed line items, including catalog objects, modifiers, and applied discounts. It also demonstrates how to apply order-level taxes and discounts. Ensure you have the necessary IDs for catalog objects and discounts.

```java
client.orders().create(
    CreateOrderRequest
        .builder()
        .order(
            Order
                .builder()
                .locationId("057P5VYJ4A5X1")
                .referenceId("my-order-001")
                .lineItems(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItem
                                .builder()
                                .quantity("1")
                                .name("New York Strip Steak")
                                .basePriceMoney(
                                    Money
                                        .builder()
                                        .amount(1599L)
                                        .currency(Currency.USD)
                                        .build()
                                )
                                .build(),
                            OrderLineItem
                                .builder()
                                .quantity("2")
                                .catalogObjectId("BEMYCSMIJL46OCDV4KYIKXIB")
                                .modifiers(
                                    Optional.of(
                                        Arrays.asList(
                                            OrderLineItemModifier
                                                .builder()
                                                .catalogObjectId("CHQX7Y4KY6N5KINJKZCFURPZ")
                                                .build()
                                        )
                                    )
                                )
                                .appliedDiscounts(
                                    Optional.of(
                                        Arrays.asList(
                                            OrderLineItemAppliedDiscount
                                                .builder()
                                                .discountUid("one-dollar-off")
                                                .build()
                                        )
                                    )
                                )
                                .build()
                        )
                    )
                )
                .taxes(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItemTax
                                .builder()
                                .uid("state-sales-tax")
                                .name("State Sales Tax")
                                .percentage("9")
                                .scope(OrderLineItemTaxScope.ORDER)
                                .build()
                        )
                    )
                )
                .discounts(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItemDiscount
                                .builder()
                                .uid("labor-day-sale")
                                .name("Labor Day Sale")
                                .percentage("5")
                                .scope(OrderLineItemDiscountScope.ORDER)
                                .build(),
                            OrderLineItemDiscount
                                .builder()
                                .uid("membership-discount")
                                .catalogObjectId("DB7L55ZH2BGWI4H23ULIWOQ7")
                                .scope(OrderLineItemDiscountScope.ORDER)
                                .build(),
                            OrderLineItemDiscount
                                .builder()
                                .uid("one-dollar-off")
                                .name("Sale - $1.00 off")
                                .amountMoney(
                                    Money
                                        .builder()
                                        .amount(100L)
                                        .currency(Currency.USD)
                                        .build()
                                )
                                .scope(OrderLineItemDiscountScope.LINE_ITEM)
                                .build()
                        )
                    )
                )
                .build()
        )
        .idempotencyKey("8193148c-9586-11e6-99f9-28cfe92138cf")
        .build()
);
```

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

### Get Team Member Wage Setting

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

Retrieves the WageSetting object for a specified team member. Square recommends using RetrieveTeamMember or SearchTeamMembers to get this information directly from the TeamMember.wage_setting field.

```APIDOC
## GET /team-members/{team_member_id}/wage-setting

### Description
Retrieves a `WageSetting` object for a team member specified by `TeamMember.id`. For more information, see [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).

Square recommends using [RetrieveTeamMember](api-endpoint:Team-RetrieveTeamMember) or [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get this information directly from the `TeamMember.wage_setting` field.

### Method
GET

### Endpoint
/v2/team-members/{team_member_id}/wage-setting

### Parameters
#### Path Parameters
- **teamMemberId** (String) - Required - The ID of the team member for which to retrieve the wage setting.

### Request Example
```java
client.teamMembers().wageSetting().get(
    GetWageSettingRequest
        .builder()
        .teamMemberId("team_member_id")
        .build()
);
```

### Response
#### Success Response (200)
- **GetWageSettingResponse** (object) - The response object for the GetWageSetting request.
```

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

### Async Client Instantiation and Usage

Source: https://context7.com/square/square-java-sdk/llms.txt

Shows how to instantiate and use the asynchronous `AsyncSquareClient` for non-blocking API calls, returning `CompletableFuture` objects. Includes an example of creating a payment.

```APIDOC
## Async Client — `AsyncSquareClient`

Drop-in async alternative to `SquareClient`; every method returns `CompletableFuture<T>` instead of `T`.

```java
import com.squareup.square.AsyncSquareClient;
import com.squareup.square.types.CreatePaymentRequest;
import com.squareup.square.types.Currency;
import com.squareup.square.types.Money;

AsyncSquareClient asyncClient = AsyncSquareClient.builder()
    .token("YOUR_SQUARE_TOKEN")
    .build();

asyncClient.payments().create(
    CreatePaymentRequest.builder()
        .sourceId("ccof:GaJGNaZa8x4OgDJn4GB")
        .idempotencyKey(java.util.UUID.randomUUID().toString())
        .amountMoney(Money.builder().amount(1000L).currency(Currency.USD).build())
        .build()
).thenAccept(response ->
    System.out.println("Payment ID: " + response.getPayment().map(p -> p.getId()).orElse("none"))
).exceptionally(ex -> {
    System.err.println("Payment failed: " + ex.getMessage());
    return null;
});
```
```

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

### Start Transfer Order

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

Changes a DRAFT transfer order to STARTED status. This decrements inventory at the source Location and marks it as in-transit. The order must be in DRAFT status and have all required fields populated.

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

### Description
Changes a DRAFT transfer order to STARTED status. This decrements inventory at the source Location and marks it as in-transit. The order must be in DRAFT status and have all required fields populated. Once started, the order can no longer be deleted, but it can be canceled via CancelTransferOrder.

Creates a `transfer_order.updated` webhook event.

### Method
POST

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

### Parameters
#### Path Parameters
- **transferOrderId** (String) - Required - The ID of the transfer order to start. Must be in DRAFT status.

#### Request Body
- **idempotencyKey** (String) - Required - A unique string that identifies this UpdateTransferOrder request. Keys can be any valid string but must be unique for every UpdateTransferOrder request.
- **version** (Optional<Long>) - Optional - Version for optimistic concurrency

### Request Example
```json
{
  "idempotencyKey": "EXAMPLE_IDEMPOTENCY_KEY_789",
  "version": 1753109537351
}
```

### Response
#### Success Response (200)
- **transferOrder** (TransferOrder) - Description of the updated transfer order
```

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

### Use Legacy SDK Alongside New SDK

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

Demonstrates how to initialize both the new and legacy Square SDK clients within the same Java file. This is useful for gradual migration.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;

SquareClient square = 
        SquareClient.builder()
                .environment(Environment.PRODUCTION)
                .token("YOUR_TOKEN")
                .build();

com.squareup.square.legacy.SquareClient legacyClient = 
        new com.squareup.square.legacy.SquareClient.Builder()
                .environment(com.squareup.square.legacy.Environment.PRODUCTION)
                .accessToken("YOUR_TOKEN")
                .build();
```

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

### List Merchants

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

Provides details about the merchant associated with a given access token. You can specify your personal access token to get your own merchant information or specify an OAuth token to get the information for the merchant that granted your application access. The cursor parameter is used for pagination.

```java
client.merchants().list(
    ListMerchantsRequest
        .builder()
        .cursor(1)
        .build()
);
```

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

### Get Device Code

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

Retrieves a DeviceCode with the associated ID.

```APIDOC
## Get Device Code

### Description
Retrieves DeviceCode with the associated ID.

### Method
GET

### Endpoint
/devices/codes/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The unique identifier for the device code.
```

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

### Configure Production Environment

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

Build the SquareClient configured for the production environment.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;

SquareClient client = SquareClient
    .builder()
    .environment(Environment.Production)
    .build();
```

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

### Get Refund

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

Retrieves a refund using its unique ID.

```APIDOC
## Get Refund

### Description
Retrieves a refund using its unique ID.

### Method
GET

### Endpoint
/v2/refunds/{refund_id}

### Parameters
#### Path Parameters
- **refund_id** (String) - Required - The unique ID for the desired `PaymentRefund`.

### Response
#### Success Response (200)
- **refund** (Refund) - Description of the refund object.

### Response Example
```json
{
  "refund": {
    "id": "string",
    "order_id": "string",
    "order_version": 0,
    "payment_id": "string",
    "reason": "string",
    "amount_money": {
      "amount": 0,
      "currency": "string"
    },
    "status": "string",
    "created_at": "string",
    "updated_at": "string",
    "refunded_money": {
      "amount": 0,
      "currency": "string"
    },
    "app_details": {
      "api_key_id": "string",
      "app_id": "string",
      "merchant_id": "string"
    },
    "location_id": "string",
    "tender_at": "string"
  }
}
```
```

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

### Create, Cancel, Complete, and List Payments

Source: https://context7.com/square/square-java-sdk/llms.txt

Demonstrates creating a payment with various options, canceling a payment by idempotency key, completing a delayed-capture payment, and paginating through a list of payments. Ensure you have the necessary imports and a SquareClient instance configured with your token.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.SquareApiException;
import com.squareup.square.types.*;

SquareClient client = SquareClient.builder().token("YOUR_SQUARE_TOKEN").build();

// Create a payment
try {
    CreatePaymentResponse resp = client.payments().create(
        CreatePaymentRequest.builder()
            .sourceId("ccof:GaJGNaZa8x4OgDJn4GB")
            .idempotencyKey("7b0f3ec5-086a-4871-8f13-3c81b3875218")
            .amountMoney(Money.builder().amount(1000L).currency(Currency.USD).build())
            .appFeeMoney(Money.builder().amount(10L).currency(Currency.USD).build())
            .autocomplete(true)
            .customerId("W92WH6P11H4Z77CTET0RNTGFW8")
            .locationId("L88917AVBK2S5")
            .referenceId("order-ref-123")
            .note("Online purchase")
            .build()
    );
    System.out.println("Created: " + resp.getPayment().map(Payment::getId).orElse("?"));
} catch (SquareApiException e) {
    System.err.println("Status " + e.getStatusCode() + ": " + e.getMessage());
}

// Cancel by idempotency key (safe retry pattern)
client.payments().cancelByIdempotencyKey(
    CancelPaymentByIdempotencyKeyRequest.builder()
        .idempotencyKey("7b0f3ec5-086a-4871-8f13-3c81b3875218")
        .build()
);

// Complete a delayed-capture payment
client.payments().complete(
    CompletePaymentRequest.builder().paymentId("PAYMENT_ID").build()
);

// Paginate all payments
for (Payment p : client.payments().list(
        ListPaymentsRequest.builder().locationId("L88917AVBK2S5").build())) {
    System.out.printf("Payment %s: %s%n", p.getId(), p.getStatus());
}
```

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

### Get Order

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

Retrieves a specific order by its unique ID.

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

### Description
Retrieves an [Order](entity:Order) by ID.

### Method
GET

### Endpoint
/v2/orders/{order_id}

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

### Response
#### Success Response (200)
- **order** (Order) - The retrieved order details.

### Request Example
```java
client.orders().get(
    GetOrdersRequest
        .builder()
        .orderId("order_id")
        .build()
);
```
```

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

### Create Order with Java SDK

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

Creates a new order with product information and purchase settings. To pay for a created order, refer to the 'Pay for Orders' documentation. Open orders can be modified using the `UpdateOrder` endpoint.

```java
client.orders.create(request)
```

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

### Create Order

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

Example of how to create a new order using the Square Java SDK. This includes specifying location, reference ID, line items, taxes, and discounts.

```APIDOC
## Create Order

### Description
Creates a new order. This operation is used to submit a new order to Square, including details about the items, taxes, and discounts.

### Method
POST (implied by SDK method `create`)

### Endpoint
(Not explicitly provided in source, inferred from SDK usage)

### Parameters
#### Request Body
- **request** (CreateOrderRequest) - Required - The request object containing the order details.

### Request Example
```java
client.orders().create(
    CreateOrderRequest
        .builder()
        .order(
            Order
                .builder()
                .locationId("057P5VYJ4A5X1")
                .referenceId("my-order-001")
                .lineItems(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItem
                                .builder()
                                .quantity("1")
                                .name("New York Strip Steak")
                                .basePriceMoney(
                                    Money
                                        .builder()
                                        .amount(1599L)
                                        .currency(Currency.USD)
                                        .build()
                                )
                                .build(),
                            OrderLineItem
                                .builder()
                                .quantity("2")
                                .catalogObjectId("BEMYCSMIJL46OCDV4KYIKXIB")
                                .modifiers(
                                    Optional.of(
                                        Arrays.asList(
                                            OrderLineItemModifier
                                                .builder()
                                                .catalogObjectId("CHQX7Y4KY6N5KINJKZCFURPZ")
                                                .build()
                                        )
                                    )
                                )
                                .appliedDiscounts(
                                    Optional.of(
                                        Arrays.asList(
                                            OrderLineItemAppliedDiscount
                                                .builder()
                                                .discountUid("one-dollar-off")
                                                .build()
                                        )
                                    )
                                )
                                .build()
                        )
                    )
                )
                .taxes(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItemTax
                                .builder()
                                .uid("state-sales-tax")
                                .name("State Sales Tax")
                                .percentage("9")
                                .scope(OrderLineItemTaxScope.ORDER)
                                .build()
                        )
                    )
                )
                .discounts(
                    Optional.of(
                        Arrays.asList(
                            OrderLineItemDiscount
                                .builder()
                                .uid("labor-day-sale")
                                .name("Labor Day Sale")
                                .percentage("5")
                                .scope(OrderLineItemDiscountScope.ORDER)
                                .build(),
                            OrderLineItemDiscount
                                .builder()
                                .uid("membership-discount")
                                .catalogObjectId("DB7L55ZH2BGWI4H23ULIWOQ7")
                                .scope(OrderLineItemDiscountScope.ORDER)
                                .build(),
                            OrderLineItemDiscount
                                .builder()
                                .uid("one-dollar-off")
                                .name("Sale - $1.00 off")
                                .amountMoney(
                                    Money
                                        .builder()
                                        .amount(100L)
                                        .currency(Currency.USD)
                                        .build()
                                )
                                .scope(OrderLineItemDiscountScope.LINE_ITEM)
                                .build()
                        )
                    )
                )
                .build()
        )
        .idempotencyKey("8193148c-9586-11e6-99f9-28cfe92138cf")
        .build()
);
```

### Response
(Response details not provided in source)
```

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

### Get Booking

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

Retrieves a specific booking using its ID.

```APIDOC
## Get Booking

### Description
Retrieves a specific booking using its ID.

### Method
GET (assumed, based on SDK method name)

### Endpoint
`/v2/bookings/{booking_id}` (inferred)

### Parameters
#### Path Parameters
- **bookingId** (String) - Required - The ID of the Booking object to retrieve.

### Request Example
```java
client.bookings().get(
    GetBookingsRequest
        .builder()
        .bookingId("booking_id")
        .build()
);
```

### Response
#### Success Response (200)
- **booking** (Booking) - The retrieved booking object.

#### Response Example
(Response structure not provided in source)
```

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

### Get Webhook Subscription

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

Retrieves a specific webhook subscription by its ID.

```APIDOC
## Get Webhook Subscription

### Description
Retrieves a webhook subscription identified by its ID.

### Method
GET

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

### Parameters
#### Path Parameters
- **subscription_id** (String) - Required - The ID of the [Subscription](entity:WebhookSubscription) to retrieve.

### Response
#### Success Response (200)
- **subscription** (WebhookSubscription) - The requested webhook subscription.

#### Response Example
```json
{
  "subscription": {
    "id": "sub_abc123",
    "name": "Example Webhook Subscription",
    "event_types": ["payment.created", "payment.updated"],
    "notification_url": "https://example-webhook-url.com",
    "api_version": "2021-12-15",
    "enabled": true,
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}
```
```

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

### Instantiate SquareClient with Explicit Token and Sandbox Environment

Source: https://context7.com/square/square-java-sdk/llms.txt

Instantiates the SquareClient with an explicitly provided token and sets the environment to SANDBOX.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;
import com.squareup.square.core.RequestOptions;
import okhttp3.OkHttpClient;

// Explicit token + sandbox environment
SquareClient client = SquareClient.builder()
    .token("YOUR_SQUARE_TOKEN")
    .environment(Environment.SANDBOX)
    .build();
```

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

### Create Payment using AsyncSquareClient

Source: https://context7.com/square/square-java-sdk/llms.txt

Demonstrates creating a payment asynchronously using AsyncSquareClient. Handles success by printing the payment ID and failure by printing an error message.

```java
import com.squareup.square.AsyncSquareClient;
import com.squareup.square.types.CreatePaymentRequest;
import com.squareup.square.types.Currency;
import com.squareup.square.types.Money;

AsyncSquareClient asyncClient = AsyncSquareClient.builder()
    .token("YOUR_SQUARE_TOKEN")
    .build();

asyncClient.payments().create(
    CreatePaymentRequest.builder()
        .sourceId("ccof:GaJGNaZa8x4OgDJn4GB")
        .idempotencyKey(java.util.UUID.randomUUID().toString())
        .amountMoney(Money.builder().amount(1000L).currency(Currency.USD).build())
        .build()
).thenAccept(response ->
    System.out.println("Payment ID: " + response.getPayment().map(p -> p.getId()).orElse("none"))
).exceptionally(ex -> {
    System.err.println("Payment failed: " + ex.getMessage());
    return null;
});
```

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

### Get Shift

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

Retrieves a single Shift specified by its unique ID.

```APIDOC
## Get Shift

### Description
Returns a single `Shift` specified by `id`.

### Method
GET

### Endpoint
/labor/shifts/{id}

### Parameters
#### Path Parameters
- **id** (String) - The UUID for the `Shift` being retrieved.

### Request Example
```java
client.labor().shifts().get(
    GetShiftsRequest
        .builder()
        .id("id")
        .build()
);
```
```

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

### Get BreakType

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

Retrieves a single BreakType specified by its unique identifier.

```APIDOC
## GET /labor/breakTypes/{id}

### Description
Returns a single `BreakType` specified by `id`.

### Method
GET

### Endpoint
/labor/breakTypes/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The UUID for the `BreakType` being retrieved.

### Request Example
```java
client.labor().breakTypes().get(
    GetBreakTypesRequest
        .builder()
        .id("id")
        .build()
);
```

### Response
#### Success Response (200)
- **breakType** (BreakType) - The requested BreakType object.
- **errors** (Error[]) - Information about errors encountered during the request.
```

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

### Create a Payment with Square Java SDK

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

Instantiate the SquareClient and use it to create a payment. Ensure you replace placeholder values like '<token>' with your actual credentials and details.

```java
package com.example.usage;

import com.squareup.square.SquareClient;
import com.squareup.square.types.CreatePaymentRequest;
import com.squareup.square.types.Currency;
import com.squareup.square.types.Money;

public class Example {
    public static void main(String[] args) {
        SquareClient client = SquareClient
            .builder()
            .token("<token>")
            .build();

        client.payments().create(
            CreatePaymentRequest
                .builder()
                .sourceId("ccof:GaJGNaZa8x4OgDJn4GB")
                .idempotencyKey("7b0f3ec5-086a-4871-8f13-3c81b3875218")
                .amountMoney(
                    Money
                        .builder()
                        .amount(1000L)
                        .currency(Currency.USD)
                        .build()
                )
                .appFeeMoney(
                    Money
                        .builder()
                        .amount(10L)
                        .currency(Currency.USD)
                        .build()
                )
                .autocomplete(true)
                .customerId("W92WH6P11H4Z77CTET0RNTGFW8")
                .locationId("L88917AVBK2S5")
                .referenceId("123456")
                .note("Brief description")
                .build()
        );
    }
}
```

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

### Configure SquareClient with Production Environment

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

Configure the SquareClient to use the production environment by specifying Environment.PRODUCTION in the builder.

```java
import com.squareup.square.SquareClient;
import com.squareup.square.core.Environment;

SquareClient square = SquareClient.builder().environment(Environment.PRODUCTION).build();
```

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

### Get Customer Segment

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

Retrieves a specific customer segment by its ID.

```APIDOC
## Get Customer Segment

### Description
Retrieves a specific customer segment as identified by the `segment_id` value.

### Method
Not specified (SDK method)

### Endpoint
Not specified (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
client.customers().segments().get(
    GetSegmentsRequest
        .builder()
        .segmentId("segment_id")
        .build()
);
```

### Response
#### Success Response
Not specified

#### Response Example
Not specified
```

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

### Create Subscription Request in Java

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

Use this snippet to enroll a customer in a subscription. Provide a location ID, customer ID, idempotency key, plan variation ID, and optionally a start date, card ID, timezone, source, and phases. If a card ID is provided, Square charges it; otherwise, an invoice is sent.

```java
client.subscriptions().create(
    CreateSubscriptionRequest
        .builder()
        .locationId("S8GWD5R9QB376")
        .customerId("CHFGVKYY8RSV93M5KCYTG4PN0G")
        .idempotencyKey("8193148c-9586-11e6-99f9-28cfe92138cf")
        .planVariationId("6JHXF3B2CW3YKHDV4XEM674H")
        .startDate("2023-06-20")
        .cardId("ccof:qy5x8hHGYsgLrp4Q4GB")
        .timezone("America/Los_Angeles")
        .source(
            SubscriptionSource
                .builder()
                .name("My Application")
                .build()
        )
        .phases(
            Optional.of(
                Arrays.asList(
                    Phase
                        .builder()
                        .ordinal(0L)
                        .orderTemplateId("U2NaowWxzXwpsZU697x7ZHOAnCNZY")
                        .build()
                )
            )
        )
        .build()
);
```

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

### Batch Get Vendors

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

Retrieves one or more vendors by their specified IDs.

```APIDOC
## Batch Get Vendors

### Description
Retrieves one or more vendors of specified Vendor IDs.

### Method
GET (inferred from SDK usage)

### Endpoint
/vendors/batch/get (inferred from SDK usage)

### Parameters
#### Request Body
- **vendorIds** (Optional<List<String>>) - Required - IDs of the Vendor objects to retrieve.

### Request Example
```java
client.vendors().batchGet(
    BatchGetVendorsRequest
        .builder()
        .vendorIds(
            Optional.of(
                Arrays.asList("INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4")
            )
        )
        .build()
);
```

### Response
#### Success Response (200)
(Response details not provided in source)

#### Response Example
(Response details not provided in source)
```

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

### Get Payment

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

Retrieves details for a specific payment using its ID.

```APIDOC
## Get Payment

### Description
Retrieves details for a specific payment.

### Method
GET (inferred from SDK usage)

### Endpoint
(Not explicitly provided, inferred from SDK usage)

### Parameters
#### Query Parameters
- **paymentId** (String) - Required - A unique ID for the desired payment.

### Request Example
```java
client.payments().get(
    GetPaymentsRequest
        .builder()
        .paymentId("payment_id")
        .build()
);
```

### Response
(Success response details not explicitly provided)

### Error Handling
(Error handling details not explicitly provided)
```

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

### List Workweek Configurations

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

Returns a list of WorkweekConfig instances for a business. Supports pagination using limit and cursor parameters.

```java
client.labor().workweekConfigs().list(
    ListWorkweekConfigsRequest
        .builder()
        .limit(1)
        .cursor("cursor")
        .build()
);
```

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

### Create Loyalty Account with Java SDK

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

Creates a new loyalty account for a customer. Requires the program ID and a mapping, typically with the customer's phone number. An idempotency key is recommended for preventing duplicate creations.

```java
client.loyalty().accounts().create(
    CreateLoyaltyAccountRequest
        .builder()
        .loyaltyAccount(
            LoyaltyAccount
                .builder()
                .programId("d619f755-2d17-41f3-990d-c04ecedd64dd")
                .mapping(
                    LoyaltyAccountMapping
                        .builder()
                        .phoneNumber("+14155551234")
                        .build()
                )
                .build()
        )
        .idempotencyKey("ec78c477-b1c3-4899-a209-a4e71337c996")
        .build()
);
```

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

### Get Invoice

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

Retrieves a specific invoice by its unique invoice ID.

```APIDOC
## GET /invoices/{invoice_id}

### Description
Retrieves an invoice by invoice ID.

### Method
GET

### Endpoint
/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoiceId** (String) - Required - The ID of the invoice to retrieve.

### Request Example
```java
client.invoices().get(
    GetInvoicesRequest
        .builder()
        .invoiceId("invoice_id")
        .build()
);
```

### Response
#### Success Response (200)
- **invoice** (Invoice) - The retrieved Invoice object.
- **errors** (List<Error>) - A list of errors that occurred during the request.
```

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

### Get Inventory Adjustment

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

Retrieves a specific inventory adjustment by its ID.

```APIDOC
## Get Inventory Adjustment

### Description
Returns the [InventoryAdjustment](entity:InventoryAdjustment) object with the provided `adjustment_id`.

### Method
GET (Assumed based on SDK method name and typical REST patterns for retrieval)

### Endpoint
/inventory/adjustments/{adjustment_id} (Assumed based on SDK method name and common REST practices)

### Parameters
#### Path Parameters
- **adjustmentId** (String) - Required - ID of the [InventoryAdjustment](entity:InventoryAdjustment) to retrieve.

### Request Example
```java
client.inventory().getAdjustment(
    GetAdjustmentInventoryRequest
        .builder()
        .adjustmentId("adjustment_id")
        .build()
);
```

### Response
#### Success Response (200)
(Response details not provided in source)
```

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

### Manage Customers with Square Java SDK

Source: https://context7.com/square/square-java-sdk/llms.txt

Use this snippet to create, bulk-create, search, update, and delete customer profiles. Ensure necessary imports are included.

```java
import com.squareup.square.types.*;
import java.util.Map;

// Create a customer
CreateCustomerResponse newCustomer = client.customers().create(
    CreateCustomerRequest.builder()
        .givenName("Jane")
        .familyName("Doe")
        .emailAddress("jane.doe@example.com")
        .phoneNumber("+14155552671")
        .referenceId("ext-crm-12345")
        .build()
);
String customerId = newCustomer.getCustomer().map(Customer::getId).orElseThrow();

// Bulk-create multiple customers at once
BulkCreateCustomersResponse bulk = client.customers().batchCreate(
    BulkCreateCustomersRequest.builder()
        .customers(Map.of(
            "ref-A", BulkCreateCustomerData.builder().givenName("Alice").emailAddress("alice@example.com").build(),
            "ref-B", BulkCreateCustomerData.builder().givenName("Bob").emailAddress("bob@example.com").build()
        ))
        .build()
);

// Search customers by email
SearchCustomersResponse found = client.customers().search(
    SearchCustomersRequest.builder()
        .query(CustomerQuery.builder()
            .filter(CustomerFilter.builder()
                .emailAddress(CustomerTextFilter.builder().exact("jane.doe@example.com").build())
                .build())
            .build())
        .build()
);

// Update, then delete
client.customers().update(UpdateCustomerRequest.builder()
    .customerId(customerId).phoneNumber("+14155559999").build());
client.customers().delete(DeleteCustomersRequest.builder().customerId(customerId).build());
```

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

### Instantiate SquareClient using Environment Variable

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

Instantiate the SquareClient without a token; it will automatically read the token from the SQUARE_TOKEN environment variable.

```java
import com.squareup.square.SquareClient;

SquareClient square = SquareClient.builder().build();
```

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

### Get Team Member Wage

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

Retrieves a single TeamMemberWage specified by its UUID.

```APIDOC
## Get Team Member Wage

### Description
Returns a single `TeamMemberWage` specified by `id`.

### Method
GET

### Endpoint
/team-member-wages/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The UUID for the `TeamMemberWage` being retrieved.

### Response
#### Success Response (200)
- **team_member_wage** (Object) - The `TeamMemberWage` object.

### Response Example
```json
{
  "team_member_wage": {
    "id": "id",
    "team_member_id": "team_member_id",
    "wage_setting": {
      "job_title": "",
      "hourly_rate": {
        "amount": 0,
        "currency": ""
      }
    },
    "version": 10
  }
}
```
```

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

### Bulk Create Customers with Java SDK

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

Use this method to create multiple customer profiles in a single request. Each customer can be identified by an idempotency key.

```java
client.customers().batchCreate(
    BulkCreateCustomersRequest
        .builder()
        .customers(
            new HashMap<String, BulkCreateCustomerData>() {{ 
                put("8bb76c4f-e35d-4c5b-90de-1194cd9179f0", BulkCreateCustomerData
                    .builder()
                    .givenName(Optional.of("Amelia"))
                    .familyName(Optional.of("Earhart"))
                    .emailAddress(Optional.of("Amelia.Earhart@example.com"))
                    .address(
                        Optional.of(
                            Address
                                .builder()
                                .addressLine1(Optional.of("500 Electric Ave"))
                                .addressLine2(Optional.of("Suite 600"))
                                .locality(Optional.of("New York"))
                                .administrativeDistrictLevel1(Optional.of("NY"))
                                .postalCode(Optional.of("10003"))
                                .country(Optional.of(Country.US))
                                .build()
                        )
                    )
                    .phoneNumber(Optional.of("+1-212-555-4240"))
                    .referenceId(Optional.of("YOUR_REFERENCE_ID"))
                    .note(Optional.of("a customer"))
                    .build());
                put("d1689f23-b25d-4932-b2f0-aed00f5e2029", BulkCreateCustomerData
                    .builder()
                    .givenName(Optional.of("Marie"))
                    .familyName(Optional.of("Curie"))
                    .emailAddress(Optional.of("Marie.Curie@example.com"))
                    .address(
                        Optional.of(
                            Address
                                .builder()
                                .addressLine1(Optional.of("500 Electric Ave"))
                                .addressLine2(Optional.of("Suite 601"))
                                .locality(Optional.of("New York"))
                                .administrativeDistrictLevel1(Optional.of("NY"))
                                .postalCode(Optional.of("10003"))
                                .country(Optional.of(Country.US))
                                .build()
                        )
                    )
                    .phoneNumber(Optional.of("+1-212-444-4240"))
                    .referenceId(Optional.of("YOUR_REFERENCE_ID"))
                    .note(Optional.of("another customer"))
                    .build());
            }}
        )
        .build()
);
```

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

### Get Customer Group

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

Retrieves a specific customer group by its unique identifier.

```APIDOC
## Get Customer Group

### Description
Retrieves a specific customer group as identified by the `group_id` value.

### Method
GET

### Endpoint
/customers/groups/{group_id}

### Parameters
#### Path Parameters
- **groupId** (String) - Required - The ID of the customer group to retrieve.

### Request Example
```java
client.customers().groups().get(
    GetGroupsRequest
        .builder()
        .groupId("group_id")
        .build()
);
```

### Response
#### Success Response (200)
- **GetCustomerGroupResponse** - The response object containing the requested customer group.
```

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

### List Workweek Configurations

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

Returns a list of WorkweekConfig instances for a business. Supports pagination.

```APIDOC
## List Workweek Configurations

### Description
Returns a list of `WorkweekConfig` instances for a business.

### Method
GET

### Endpoint
/workweek-configs

### Parameters
#### Query Parameters
- **limit** (Integer) - Optional - The maximum number of `WorkweekConfigs` results to return per page.
- **cursor** (String) - Optional - A pointer to the next page of `WorkweekConfig` results to fetch.

### Response
#### Success Response (200)
- **workweek_configs** (Array) - A list of `WorkweekConfig` objects.
- **cursor** (String) - A pointer to the next page of results.

### Response Example
```json
{
  "workweek_configs": [
    {
      "id": "id",
      "business_id": "business_id",
      "start_of_week": "MON",
      "start_of_day_local_time": "10:00",
      "version": 10
    }
  ],
  "cursor": "cursor"
}
```
```

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

### Get Vendor

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

Retrieves the details of a specific vendor using their unique ID.

```APIDOC
## Get Vendor

### Description
Retrieves the vendor of a specified Vendor ID.

### Method
GET

### Endpoint
/vendors/{vendor_id}

### Parameters
#### Path Parameters
- **vendorId** (String) - Required - ID of the Vendor to retrieve.
```

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

### Create Subscription using Square Java SDK

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

Initiates the creation of a subscription using the Square Java SDK. This is the starting point for managing recurring payments.

```java
client.subscriptions().create(request);
```

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

### Get Dispute

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

Returns details about a specific dispute using its unique ID.

```APIDOC
## Get Dispute

### Description
Returns details about a specific dispute using its unique ID.

### Method
```java
client.disputes().get(disputeId)
```

### Parameters
#### Path Parameters
- **disputeId** (String) - The ID of the dispute you want more details about.
```

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

### Get Device

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

Retrieves details for a specific device using its unique ID.

```APIDOC
## Get Device

### Description
Retrieves details for a specific device using its unique ID.

### Method
```java
client.devices().get(deviceId)
```

### Parameters
#### Path Parameters
- **deviceId** (String) - The unique ID for the desired `Device`.
```

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

### List Loyalty Programs in Java

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

Retrieve a list of all loyalty programs associated with the seller's account. Note that sellers can only have one active loyalty program.

```java
client.loyalty().programs().list();
```

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

### Create Booking with Java SDK

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

Creates a booking. Requires specific booking details including location ID, start time, team member ID, service variation ID, and service variation version. Permissions and subscription levels are necessary for seller-level access.

```java
client.bookings().create(
    CreateBookingRequest
        .builder()
        .booking(
            Booking
                .builder()
                .build()
        )
        .build()
);
```

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

### Get Customer

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

Retrieves details for a single customer using their unique ID.

```APIDOC
## GET /customers/{customerId}

### Description
Returns details for a single customer.

### Method
GET

### Endpoint
/customers/{customerId}

### Parameters
#### Path Parameters
- **customerId** (String) - Required - The ID of the customer to retrieve.

### Response
#### Success Response (200)
- **Customer** (object) - Details of the customer.

### Request Example
```java
client.customers().get(
    GetCustomersRequest
        .builder()
        .customerId("customer_id")
        .build()
);
```
```

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

### Instantiate SquareClient with Token

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

Instantiate the SquareClient by providing your Square API token directly during builder configuration.

```java
import com.squareup.square.SquareClient;

SquareClient square = SquareClient.builder().token("SQUARE_TOKEN").build();
```
Tokens:
Raw