square.rb 10.0.0.20210421 → 13.0.0.20210721

data/lib/square/api/loyalty_api.rb

@@ -6,8 +6,7 @@ module Square
     end
 
     # Creates a loyalty account. To create a loyalty account, you must provide
-    # the `program_id` and either the `mapping` field (preferred) or the
-    # `mappings` field.
+    # 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.
@@ -121,12 +120,16 @@ module Square
     # account.
     # - 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
+    # For spend-based and visit-based programs, you can first call
     # [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.
+    # points
+    # that you provide to this endpoint.
+    # __Note:__ The country of the seller's Square account determines whether
+    # tax is included in the purchase amount when accruing points for
+    # spend-based and visit-based programs.
+    # For more information, see [Availability of Square
+    # Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-
+    # market-availability).
     # @param [String] account_id Required parameter: The [loyalty
     # account]($m/LoyaltyAccount) ID to which to add the points.
     # @param [AccumulateLoyaltyPointsRequest] body Required parameter: An object
@@ -254,9 +257,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'
@@ -335,6 +345,12 @@ module Square
     # An application might call this endpoint to show the points that a buyer
     # can earn with the
     # specific purchase.
+    # __Note:__ The country of the seller's Square account determines whether
+    # tax is included in the purchase amount when accruing points for
+    # spend-based and visit-based programs.
+    # For more information, see [Availability of Square
+    # Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-
+    # market-availability).
     # @param [String] program_id Required parameter: The [loyalty
     # program]($m/LoyaltyProgram) ID, which defines the rules for accruing
     # points.

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,13 +5,12 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a new [Order]($m/Order) which can include information on products
-    # for
+    # 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
+    # To pay for a created order, see
     # [Pay for
-    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
-    # guide.
+    # 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
@@ -47,8 +46,8 @@ module Square
       )
     end
 
-    # Retrieves a set of [Order]($m/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
@@ -119,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`]($m/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
+    #   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.
@@ -201,24 +201,24 @@ module Square
       )
     end
 
-    # Updates an open [Order]($m/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
+    # identifying the fields to clear.
+    # To pay for an order, see
     # [Pay for
-    # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
-    # guide.
+    # 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
@@ -260,23 +260,23 @@ module Square
     end
 
     # Pay for an [order]($m/Order) using one or more approved
-    # [payments]($m/Payment),
+    # [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]($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/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

data/lib/square/api/snippets_api.rb

@@ -0,0 +1,146 @@
+module Square
+  # SnippetsApi
+  class SnippetsApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Removes your snippet from a Square Online site.
+    # You can call [ListSites]($e/Sites/ListSites) to get the IDs of the 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).
+    # @param [String] site_id Required parameter: The ID of the site that
+    # contains the snippet.
+    # @return [DeleteSnippetResponse Hash] response from the API call
+    def delete_snippet(site_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/sites/{site_id}/snippet'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'site_id' => { 'value' => site_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.delete(
+        _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
+
+    # Retrieves your snippet from a Square Online site. A site can contain
+    # snippets from multiple snippet applications, but you can retrieve only the
+    # snippet that was added by your application.
+    # You can call [ListSites]($e/Sites/ListSites) to get the IDs of the 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).
+    # @param [String] site_id Required parameter: The ID of the site that
+    # contains the snippet.
+    # @return [RetrieveSnippetResponse Hash] response from the API call
+    def retrieve_snippet(site_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/sites/{site_id}/snippet'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'site_id' => { 'value' => site_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
+
+    # Adds a snippet to a Square Online site or updates the existing snippet on
+    # the site.
+    # The snippet code is appended to the end of the `head` element on every
+    # page of the site, except checkout pages. A snippet application can add one
+    # snippet to a given site.
+    # You can call [ListSites]($e/Sites/ListSites) to get the IDs of the 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).
+    # @param [String] site_id Required parameter: The ID of the site where you
+    # want to add or update the snippet.
+    # @param [UpsertSnippetRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [UpsertSnippetResponse Hash] response from the API call
+    def upsert_snippet(site_id:,
+                       body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/sites/{site_id}/snippet'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'site_id' => { 'value' => site_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      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

data/lib/square/api/team_api.rb

@@ -5,12 +5,12 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a single `TeamMember` object. The `TeamMember` will be returned on
-    # successful creates.
+    # Creates a single `TeamMember` object. The `TeamMember` object is returned
+    # on successful creates.
     # You must provide the following values in your request to this endpoint:
     # - `given_name`
     # - `family_name`
-    # Learn about [Troubleshooting the Teams
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#createteamme
     # mber).
     # @param [CreateTeamMemberRequest] body Required parameter: An object
@@ -47,13 +47,13 @@ module Square
     end
 
     # Creates multiple `TeamMember` objects. The created `TeamMember` objects
-    # will be returned on successful creates.
-    # This process is non-transactional and will process as much of the request
-    # as is possible. If one of the creates in
-    # the request cannot be successfully processed, the request will NOT be
-    # marked as failed, but the body of the response
-    # will contain explicit error information for this particular create.
-    # Learn about [Troubleshooting the Teams
+    # are returned on successful creates.
+    # This process is non-transactional and processes as much of the request as
+    # possible. If one of the creates in
+    # the request cannot be successfully processed, the request is not marked as
+    # failed, but the body of the response
+    # contains explicit error information for the failed create.
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#bulk-create-
     # team-members).
     # @param [BulkCreateTeamMembersRequest] body Required parameter: An object
@@ -90,13 +90,13 @@ module Square
     end
 
     # Updates multiple `TeamMember` objects. The updated `TeamMember` objects
-    # will be returned on successful updates.
-    # This process is non-transactional and will process as much of the request
-    # as is possible. If one of the updates in
-    # the request cannot be successfully processed, the request will NOT be
-    # marked as failed, but the body of the response
-    # will contain explicit error information for this particular update.
-    # Learn about [Troubleshooting the Teams
+    # are returned on successful updates.
+    # This process is non-transactional and processes as much of the request as
+    # possible. If one of the updates in
+    # the request cannot be successfully processed, the request is not marked as
+    # failed, but the body of the response
+    # contains explicit error information for the failed update.
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#bulk-update-
     # team-members).
     # @param [BulkUpdateTeamMembersRequest] body Required parameter: An object
@@ -133,8 +133,8 @@ module Square
     end
 
     # Returns a paginated list of `TeamMember` objects for a business.
-    # The list to be returned can be filtered by:
-    # - location IDs **and**
+    # The list can be filtered by the following:
+    # - location IDs
     # - `status`
     # @param [SearchTeamMembersRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -169,8 +169,8 @@ module Square
       )
     end
 
-    # Retrieve a `TeamMember` object for the given `TeamMember.id`.
-    # Learn about [Troubleshooting the Teams
+    # Retrieves a `TeamMember` object for the given `TeamMember.id`.
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#retrieve-a-t
     # eam-member).
     # @param [String] team_member_id Required parameter: The ID of the team
@@ -207,9 +207,9 @@ module Square
       )
     end
 
-    # Updates a single `TeamMember` object. The `TeamMember` will be returned on
-    # successful updates.
-    # Learn about [Troubleshooting the Teams
+    # Updates a single `TeamMember` object. The `TeamMember` object is returned
+    # on successful updates.
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#update-a-tea
     # m-member).
     # @param [String] team_member_id Required parameter: The ID of the team
@@ -252,13 +252,13 @@ module Square
       )
     end
 
-    # Retrieve a `WageSetting` object for a team member specified
+    # Retrieves a `WageSetting` object for a team member specified
     # by `TeamMember.id`.
-    # Learn about [Troubleshooting the Teams
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#retrievewage
     # setting).
     # @param [String] team_member_id Required parameter: The ID of the team
-    # member to retrieve wage setting for
+    # member for which to retrieve the wage setting.
     # @return [RetrieveWageSettingResponse Hash] response from the API call
     def retrieve_wage_setting(team_member_id:)
       # Prepare query url.
@@ -295,12 +295,12 @@ module Square
     # `WageSetting` with the specified `team_member_id` does not exist.
     # Otherwise,
     # it fully replaces the `WageSetting` object for the team member.
-    # The `WageSetting` will be returned upon successful update.
-    # Learn about [Troubleshooting the Teams
+    # The `WageSetting` is returned on a successful update.
+    # Learn about [Troubleshooting the Team
     # API](https://developer.squareup.com/docs/team/troubleshooting#create-or-up
     # date-a-wage-setting).
     # @param [String] team_member_id Required parameter: The ID of the team
-    # member to update the `WageSetting` object for.
+    # member for which to update the `WageSetting` object.
     # @param [UpdateWageSettingRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.