square.rb 9.1.0.20210317 → 12.0.0.20210616

data/lib/square/api/locations_api.rb

@@ -7,8 +7,7 @@ module Square
 
     # Provides information of all locations of a business.
     # Many Square API endpoints require a `location_id` parameter.
-    # The `id` field of the [`Location`](#type-location) objects returned by
-    # this
+    # The `id` field of the [`Location`]($m/Location) objects returned by this
     # endpoint correspond to that `location_id` parameter.
     # @return [ListLocationsResponse Hash] response from the API call
     def list_locations

data/lib/square/api/loyalty_api.rb

@@ -5,7 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a loyalty account.
+    # 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.
     # @param [CreateLoyaltyAccountRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -79,7 +80,7 @@ module Square
 
     # Retrieves a loyalty account.
     # @param [String] account_id Required parameter: The ID of the [loyalty
-    # account](#type-LoyaltyAccount) to retrieve.
+    # account]($m/LoyaltyAccount) to retrieve.
     # @return [RetrieveLoyaltyAccountResponse Hash] response from the API call
     def retrieve_loyalty_account(account_id:)
       # Prepare query url.
@@ -120,13 +121,13 @@ module Square
     # - If you are not using the Orders API to manage orders,
     # you first perform a client-side computation to compute the points.
     # For spend-based and visit-based programs, you can call
-    # [CalculateLoyaltyPoints](#endpoint-Loyalty-CalculateLoyaltyPoints) to
-    # compute the points. For more information,
+    # [CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute the
+    # points. For more information,
     # see [Loyalty Program
     # Overview](https://developer.squareup.com/docs/loyalty/overview).
     # You then provide the points in a request to this endpoint.
     # @param [String] account_id Required parameter: The [loyalty
-    # account](#type-LoyaltyAccount) ID to which to add the points.
+    # account]($m/LoyaltyAccount) ID to which to add the points.
     # @param [AccumulateLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -168,10 +169,10 @@ module Square
     # Adds points to or subtracts points from a buyer's account.
     # Use this endpoint only when you need to manually adjust points. Otherwise,
     # in your application flow, you call
-    # [AccumulateLoyaltyPoints](#endpoint-Loyalty-AccumulateLoyaltyPoints)
+    # [AccumulateLoyaltyPoints]($e/Loyalty/AccumulateLoyaltyPoints)
     # to add points when a buyer pays for the purchase.
     # @param [String] account_id Required parameter: The ID of the [loyalty
-    # account](#type-LoyaltyAccount) in which to adjust the points.
+    # account]($m/LoyaltyAccount) in which to adjust the points.
     # @param [AdjustLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -217,6 +218,7 @@ module Square
     # (for example, points earned, points redeemed, and points expired) is
     # recorded in the ledger. Using this endpoint, you can search the ledger for
     # events.
+    # Search results are sorted by `created_at` in descending order.
     # @param [SearchLoyaltyEventsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -251,9 +253,16 @@ module Square
     end
 
     # Returns a list of loyalty programs in the seller's account.
-    # Currently, a seller can only have one loyalty program.
+    # 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]($e/Loyalty/RetrieveLoyaltyProgram)
+    # when used with the keyword `main`.
     # @return [ListLoyaltyProgramsResponse Hash] response from the API call
     def list_loyalty_programs
+      warn 'Endpoint list_loyalty_programs in LoyaltyApi is deprecated'
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/loyalty/programs'
@@ -280,6 +289,48 @@ module Square
       )
     end
 
+    # Retrieves the loyalty program in a seller's account, specified by the
+    # program ID or the keyword `main`.
+    # 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).
+    # @param [String] program_id Required parameter: The ID of the loyalty
+    # program or the keyword `main`. Either value can be used to retrieve the
+    # single loyalty program that belongs to the seller.
+    # @return [RetrieveLoyaltyProgramResponse Hash] response from the API call
+    def retrieve_loyalty_program(program_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/loyalty/programs/{program_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'program_id' => { 'value' => program_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.get(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+
     # Calculates the points a purchase earns.
     # - If you are using the Orders API to manage orders, you provide `order_id`
     # in the request. The
@@ -291,7 +342,7 @@ module Square
     # can earn with the
     # specific purchase.
     # @param [String] program_id Required parameter: The [loyalty
-    # program](#type-LoyaltyProgram) ID, which defines the rules for accruing
+    # program]($m/LoyaltyProgram) ID, which defines the rules for accruing
     # points.
     # @param [CalculateLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -376,7 +427,8 @@ module Square
     # In the current implementation, the endpoint supports search by the reward
     # `status`.
     # If you know a reward ID, use the
-    # [RetrieveLoyaltyReward](#endpoint-Loyalty-RetrieveLoyaltyReward) endpoint.
+    # [RetrieveLoyaltyReward]($e/Loyalty/RetrieveLoyaltyReward) endpoint.
+    # Search results are sorted by `updated_at` in descending order.
     # @param [SearchLoyaltyRewardsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -413,12 +465,12 @@ module Square
     # Deletes a loyalty reward by doing the following:
     # - Returns the loyalty points back to the loyalty account.
     # - If an order ID was specified when the reward was created
-    # (see [CreateLoyaltyReward](#endpoint-Loyalty-CreateLoyaltyReward)),
+    # (see [CreateLoyaltyReward]($e/Loyalty/CreateLoyaltyReward)),
     # it updates the order by removing the reward and related
     # discounts.
     # You cannot delete a reward that has reached the terminal state (REDEEMED).
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to delete.
+    # reward]($m/LoyaltyReward) to delete.
     # @return [DeleteLoyaltyRewardResponse Hash] response from the API call
     def delete_loyalty_reward(reward_id:)
       # Prepare query url.
@@ -453,7 +505,7 @@ module Square
 
     # Retrieves a loyalty reward.
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to retrieve.
+    # reward]($m/LoyaltyReward) to retrieve.
     # @return [RetrieveLoyaltyRewardResponse Hash] response from the API call
     def retrieve_loyalty_reward(reward_id:)
       # Prepare query url.
@@ -495,7 +547,7 @@ module Square
     # In other words, points used for the reward cannot be returned
     # to the account.
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to redeem.
+    # reward]($m/LoyaltyReward) to redeem.
     # @param [RedeemLoyaltyRewardRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.

data/lib/square/api/merchants_api.rb

@@ -12,7 +12,7 @@ module Square
     # information or specify an OAuth token
     # to get the information for the  merchant that granted you access.
     # If you know the merchant ID, you can also use the
-    # [RetrieveMerchant](#endpoint-merchants-retrievemerchant)
+    # [RetrieveMerchant]($e/Merchants/RetrieveMerchant)
     # endpoint to get the merchant information.
     # @param [Integer] cursor Optional parameter: The cursor generated by the
     # previous response.

data/lib/square/api/o_auth_api.rb

@@ -7,9 +7,9 @@ module Square
 
     # `RenewToken` is deprecated. For information about refreshing OAuth access
     # tokens, see
-    # [Renew OAuth
-    # Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth-
-    # tokens).
+    # [Migrate from Renew to Refresh OAuth
+    # Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-t
+    # okens).
     # Renews an OAuth access token before it expires.
     # OAuth access tokens besides your application's personal access token
     # expire after __30 days__.
@@ -25,10 +25,10 @@ module Square
     # ```
     # Replace `APPLICATION_SECRET` with the application secret on the
     # Credentials
-    # page in the [application dashboard](https://connect.squareup.com/apps).
+    # page in the [developer dashboard](https://developer.squareup.com/apps).
     # @param [String] client_id Required parameter: Your application ID,
-    # available from the [application
-    # dashboard](https://connect.squareup.com/apps).
+    # available from the [developer
+    # dashboard](https://developer.squareup.com/apps).
     # @param [RenewTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -83,9 +83,8 @@ module Square
     # ```
     # Authorization: Client APPLICATION_SECRET
     # ```
-    # Replace `APPLICATION_SECRET` with the application secret on the
-    # Credentials
-    # page in the [Developer Dashboard](https://developer.squareup.com/apps).
+    # Replace `APPLICATION_SECRET` with the application secret on the OAuth
+    # page in the [developer dashboard](https://developer.squareup.com/apps).
     # @param [RevokeTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.

data/lib/square/api/orders_api.rb

@@ -5,14 +5,14 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a new [Order](#type-order) which can include information on
+    # Creates a new [order]($m/Order) that can include information about
     # products for
     # purchase and settings to apply to the purchase.
-    # To pay for a created order, please refer to the [Pay for
-    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
-    # guide.
-    # You can modify open orders using the
-    # [UpdateOrder](#endpoint-orders-updateorder) endpoint.
+    # To pay for a created order, see
+    # [Pay for
+    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
+    # You can modify open orders using the [UpdateOrder]($e/Orders/UpdateOrder)
+    # endpoint.
     # @param [CreateOrderRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -46,8 +46,8 @@ module Square
       )
     end
 
-    # Retrieves a set of [Order](#type-order)s by their IDs.
-    # If a given Order ID does not exist, the ID is ignored instead of
+    # Retrieves a set of [orders]($m/Order) by their IDs.
+    # If a given order ID does not exist, the ID is ignored instead of
     # generating an error.
     # @param [BatchRetrieveOrdersRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -82,7 +82,7 @@ module Square
       )
     end
 
-    # Calculates an [Order](#type-order).
+    # Enables applications to preview order pricing without creating an order.
     # @param [CalculateOrderRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -118,17 +118,18 @@ module Square
 
     # Search all orders for one or more locations. Orders include all sales,
     # returns, and exchanges regardless of how or when they entered the Square
-    # Ecosystem (e.g. Point of Sale, Invoices, Connect APIs, etc).
-    # SearchOrders requests need to specify which locations to search and define
-    # a
-    # [`SearchOrdersQuery`](#type-searchordersquery) object which controls
-    # how to sort or filter the results. Your SearchOrdersQuery can:
+    # ecosystem (such as Point of Sale, Invoices, and Connect APIs).
+    # `SearchOrders` requests need to specify which locations to search and
+    # define a
+    # [SearchOrdersQuery]($m/SearchOrdersQuery) object that controls
+    # how to sort or filter the results. Your `SearchOrdersQuery` can:
     #   Set filter criteria.
-    #   Set sort order.
-    #   Determine whether to return results as complete Order objects, or as
-    # [OrderEntry](#type-orderentry) objects.
+    #   Set the sort order.
+    #   Determine whether to return results as complete `Order` objects or as
+    # [OrderEntry]($m/OrderEntry) objects.
     # Note that details for orders processed with Square Point of Sale while in
-    # offline mode may not be transmitted to Square for up to 72 hours. Offline
+    # offline mode might not be transmitted to Square for up to 72 hours.
+    # Offline
     # orders have a `created_at` value that reflects the time the order was
     # created,
     # not the time it was subsequently transmitted to Square.
@@ -165,7 +166,7 @@ module Square
       )
     end
 
-    # Retrieves an [Order](#type-order) by ID.
+    # Retrieves an [Order]($m/Order) by ID.
     # @param [String] order_id Required parameter: The ID of the order to
     # retrieve.
     # @return [RetrieveOrderResponse Hash] response from the API call
@@ -200,23 +201,24 @@ module Square
       )
     end
 
-    # Updates an open [Order](#type-order) by adding, replacing, or deleting
+    # Updates an open [order]($m/Order) by adding, replacing, or deleting
     # fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.
-    # An UpdateOrder request requires the following:
+    # An `UpdateOrder` request requires the following:
     # - The `order_id` in the endpoint path, identifying the order to update.
     # - The latest `version` of the order to update.
     # - The [sparse
     # order](https://developer.squareup.com/docs/orders-api/manage-orders#sparse
     # -order-objects)
-    # containing only the fields to update and the version the update is
-    # being applied to.
+    # containing only the fields to update and the version to which the update
+    # is
+    # being applied.
     # - If deleting fields, the [dot notation
     # paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot
     # -notation)
-    # identifying fields to clear.
-    # To pay for an order, please refer to the [Pay for
-    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
-    # guide.
+    # identifying the fields to clear.
+    # To pay for an order, see
+    # [Pay for
+    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
     # @param [String] order_id Required parameter: The ID of the order to
     # update.
     # @param [UpdateOrderRequest] body Required parameter: An object containing
@@ -257,24 +259,24 @@ module Square
       )
     end
 
-    # Pay for an [order](#type-order) using one or more approved
-    # [payments](#type-payment),
+    # Pay for an [order]($m/Order) using one or more approved
+    # [payments]($m/Payment)
     # or settle an order with a total of `0`.
     # The total of the `payment_ids` listed in the request must be equal to the
     # order
     # total. Orders with a total amount of `0` can be marked as paid by
     # specifying an empty
     # array of `payment_ids` in the request.
-    # To be used with PayOrder, a payment must:
+    # To be used with `PayOrder`, a payment must:
     # - Reference the order by specifying the `order_id` when [creating the
-    # payment](#endpoint-payments-createpayment).
+    # payment]($e/Payments/CreatePayment).
     # Any approved payments that reference the same `order_id` not specified in
     # the
-    # `payment_ids` will be canceled.
+    # `payment_ids` is canceled.
     # - Be approved with [delayed
     # capture](https://developer.squareup.com/docs/payments-api/take-payments#de
     # layed-capture).
-    # Using a delayed capture payment with PayOrder will complete the approved
+    # Using a delayed capture payment with `PayOrder` completes the approved
     # payment.
     # @param [String] order_id Required parameter: The ID of the order being
     # paid.

data/lib/square/api/payments_api.rb

@@ -6,6 +6,9 @@ module Square
     end
 
     # Retrieves a list of payments taken by the account making the request.
+    # Results are eventually consistent, and new payments or changes to payments
+    # might take several
+    # seconds to appear.
     # The maximum results per page is 100.
     # @param [String] begin_time Optional parameter: The timestamp for the
     # beginning of the reporting period, in RFC 3339 format. Inclusive. Default:
@@ -88,7 +91,7 @@ module Square
     # Square gift card) or record a payment that the seller received outside of
     # Square
     # (cash payment from a buyer or a payment that an external entity
-    # procesed on behalf of the seller).
+    # processed on behalf of the seller).
     # The endpoint creates a
     # `Payment` object and returns it in the response.
     # @param [CreatePaymentRequest] body Required parameter: An object

data/lib/square/api/refunds_api.rb

@@ -6,6 +6,9 @@ module Square
     end
 
     # Retrieves a list of refunds for the account making the request.
+    # Results are eventually consistent, and new refunds or changes to refunds
+    # might take several
+    # seconds to appear.
     # The maximum results per page is 100.
     # @param [String] begin_time Optional parameter: The timestamp for the
     # beginning of the requested reporting period, in RFC 3339 format.  Default:
@@ -26,7 +29,7 @@ module Square
     # associated with the seller.
     # @param [String] status Optional parameter: If provided, only refunds with
     # the given status are returned. For a list of refund status values, see
-    # [PaymentRefund](#type-paymentrefund).  Default: If omitted, refunds are
+    # [PaymentRefund]($m/PaymentRefund).  Default: If omitted, refunds are
     # returned regardless of their status.
     # @param [String] source_type Optional parameter: If provided, only refunds
     # with the given source type are returned. - `CARD` - List refunds only for

data/lib/square/api/sites_api.rb

@@ -0,0 +1,42 @@
+module Square
+  # SitesApi
+  class SitesApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Lists the Square Online sites that belong to a seller.
+    # __Note:__ Square Online APIs are publicly available as part of an early
+    # access program. For more information, see [Early access program for Square
+    # Online
+    # APIs](https://developer.squareup.com/docs/online-api#early-access-program-
+    # for-square-online-apis).
+    # @return [ListSitesResponse Hash] response from the API call
+    def list_sites
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/sites'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.get(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+  end
+end