square.rb 6.5.0.20201028 → 9.1.0.20210317

data/lib/square/api/cash_drawers_api.rb

@@ -63,7 +63,8 @@ module Square
     end
 
     # Provides the summary details for a single cash drawer shift. See
-    # RetrieveCashDrawerShiftEvents for a list of cash drawer shift events.
+    # [ListCashDrawerShiftEvents](#endpoint-CashDrawers-ListCashDrawerShiftEvent
+    # s) for a list of cash drawer shift events.
     # @param [String] location_id Required parameter: The ID of the location to
     # retrieve cash drawer shifts from.
     # @param [String] shift_id Required parameter: The shift ID.

data/lib/square/api/catalog_api.rb

@@ -239,9 +239,9 @@ module Square
     # `DISCOUNT`, `TAX`, `IMAGE`.
     # __Important:__ ListCatalog does not return deleted catalog items. To
     # retrieve
-    # deleted catalog items, use SearchCatalogObjects and set
-    # `include_deleted_objects`
-    # to `true`.
+    # deleted catalog items, use
+    # [SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
+    # and set the `include_deleted_objects` attribute value to `true`.
     # @param [String] cursor Optional parameter: The pagination cursor returned
     # in the previous response. Leave unset for an initial request. See
     # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
@@ -251,16 +251,23 @@ module Square
     # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.  The legal values are taken from the
     # CatalogObjectType enum: `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`,
     # `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.
+    # @param [Long] catalog_version Optional parameter: The specific version of
+    # the catalog objects to be included in the response.  This allows you to
+    # retrieve historical versions of objects. The specified version value is
+    # matched against the [CatalogObject](#type-catalogobject)s' `version`
+    # attribute.
     # @return [ListCatalogResponse Hash] response from the API call
     def list_catalog(cursor: nil,
-                     types: nil)
+                     types: nil,
+                     catalog_version: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/catalog/list'
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
         'cursor' => cursor,
-        'types' => types
+        'types' => types,
+        'catalog_version' => catalog_version
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -382,9 +389,15 @@ module Square
     # response contains a `CatalogItemVariation`, its parent `CatalogItem` will
     # be returned in the `related_objects` field of the response.  Default
     # value: `false`
+    # @param [Long] catalog_version Optional parameter: Requests objects as of a
+    # specific version of the catalog. This allows you to retrieve historical
+    # versions of objects. The value to retrieve a specific version of an object
+    # can be found in the version field of
+    # [CatalogObject](#type-catalogobject)s.
     # @return [RetrieveCatalogObjectResponse Hash] response from the API call
     def retrieve_catalog_object(object_id:,
-                                include_related_objects: false)
+                                include_related_objects: false,
+                                catalog_version: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/catalog/object/{object_id}'
@@ -394,7 +407,8 @@ module Square
       )
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
-        'include_related_objects' => include_related_objects
+        'include_related_objects' => include_related_objects,
+        'catalog_version' => catalog_version
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -419,10 +433,10 @@ module Square
       )
     end
 
-    # Searches for [CatalogObject](#type-CatalogObject) of any types against
+    # Searches for [CatalogObject](#type-CatalogObject) of any type by matching
     # supported search attribute values,
     # excluding custom attribute values on items or item variations, against one
-    # or more of the specified query expressions,
+    # or more of the specified query expressions.
     # This (`SearchCatalogObjects`) endpoint differs from the
     # [SearchCatalogItems](#endpoint-Catalog-SearchCatalogItems)
     # endpoint in the following aspects:
@@ -472,7 +486,7 @@ module Square
     # Searches for catalog items or item variations by matching supported search
     # attribute values, including
     # custom attribute values, against one or more of the specified query
-    # expressions,
+    # expressions.
     # This (`SearchCatalogItems`) endpoint differs from the
     # [SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
     # endpoint in the following aspects:

data/lib/square/api/checkout_api.rb

@@ -5,8 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Links a `checkoutId` to a `checkout_page_url` that customers will
-    # be directed to in order to provide their payment information using a
+    # Links a `checkoutId` to a `checkout_page_url` that customers are
+    # directed to in order to provide their payment information using a
     # payment processing workflow hosted on connect.squareup.com.
     # @param [String] location_id Required parameter: The ID of the business
     # location to associate the checkout with.

data/lib/square/api/customer_segments_api.rb

@@ -9,8 +9,8 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # previous calls to __ListCustomerSegments__. Used to retrieve the next set
     # of query results.  See the [Pagination
-    # guide](https://developer.squareup.com/docs/docs/working-with-apis/paginati
-    # on) for more information.
+    # guide](https://developer.squareup.com/docs/working-with-apis/pagination)
+    # for more information.
     # @return [ListCustomerSegmentsResponse Hash] response from the API call
     def list_customer_segments(cursor: nil)
       # Prepare query url.

data/lib/square/api/disputes_api.rb

@@ -5,20 +5,19 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns a list of disputes associated
-    # with a particular account.
+    # Returns a list of disputes associated with a particular account.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
-    # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for the original query. For more information, see
-    # [Paginating](https://developer.squareup.com/docs/basics/api101/pagination)
+    # a previous call to this endpoint. Provide this cursor to retrieve the next
+    # set of results for the original query. For more information, see
+    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
     # .
     # @param [DisputeState] states Optional parameter: The dispute states to
     # filter the result. If not specified, the endpoint returns all open
-    # disputes (dispute status is not `INQUIRY_CLOSED`, `WON`, or `LOST`).
+    # disputes (the dispute status is not `INQUIRY_CLOSED`, `WON`, or `LOST`).
     # @param [String] location_id Optional parameter: The ID of the location for
-    # which to return  a list of disputes. If not specified, the endpoint
-    # returns all open disputes (dispute status is not `INQUIRY_CLOSED`, `WON`,
-    # or  `LOST`) associated with all locations.
+    # which to return a list of disputes. If not specified, the endpoint returns
+    # all open disputes (the dispute status is not `INQUIRY_CLOSED`, `WON`, or
+    # `LOST`) associated with all locations.
     # @return [ListDisputesResponse Hash] response from the API call
     def list_disputes(cursor: nil,
                       states: nil,
@@ -55,7 +54,7 @@ module Square
       )
     end
 
-    # Returns details of a specific dispute.
+    # Returns details about a specific dispute.
     # @param [String] dispute_id Required parameter: The ID of the dispute you
     # want more details about.
     # @return [RetrieveDisputeResponse Hash] response from the API call
@@ -90,14 +89,14 @@ module Square
       )
     end
 
-    # Accepts loss on a dispute. Square returns
-    # the disputed amount to the cardholder and updates the
-    # dispute state to ACCEPTED.
-    # Square debits the disputed amount from the seller’s Square
-    # account. If the Square account balance does not have
-    # sufficient funds, Square debits the associated bank account.
-    # @param [String] dispute_id Required parameter: ID of the dispute you want
-    # to accept.
+    # Accepts the loss on a dispute. Square returns the disputed amount to the
+    # cardholder and
+    # updates the dispute state to ACCEPTED.
+    # Square debits the disputed amount from the seller’s Square account. If the
+    # Square account
+    # does not have sufficient funds, Square debits the associated bank account.
+    # @param [String] dispute_id Required parameter: The ID of the dispute you
+    # want to accept.
     # @return [AcceptDisputeResponse Hash] response from the API call
     def accept_dispute(dispute_id:)
       # Prepare query url.
@@ -165,8 +164,8 @@ module Square
     end
 
     # Removes specified evidence from a dispute.
-    # Square does not send the bank any evidence that
-    # is removed. Also, you cannot remove evidence after
+    # Square does not send the bank any evidence that is removed. Also, you
+    # cannot remove evidence after
     # submitting it to the bank using
     # [SubmitEvidence](https://developer.squareup.com/docs/reference/square/disp
     # utes-api/submit-evidence).
@@ -210,8 +209,8 @@ module Square
 
     # Returns the specific evidence metadata associated with a specific dispute.
     # You must maintain a copy of the evidence you upload if you want to
-    # reference it later. You cannot download the evidence
-    # after you upload it.
+    # reference it later. You cannot
+    # download the evidence after you upload it.
     # @param [String] dispute_id Required parameter: The ID of the dispute that
     # you want to retrieve evidence from.
     # @param [String] evidence_id Required parameter: The ID of the evidence to
@@ -251,13 +250,13 @@ module Square
     end
 
     # Uploads a file to use as evidence in a dispute challenge. The endpoint
-    # accepts
-    # HTTP multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG,
-    # and TIFF formats.
-    # @param [String] dispute_id Required parameter: ID of the dispute you want
-    # to upload evidence for.
+    # accepts HTTP
+    # multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG, and TIFF
+    # formats.
+    # @param [String] dispute_id Required parameter: The ID of the dispute you
+    # want to upload evidence for.
     # @param [CreateDisputeEvidenceFileRequest] request Optional parameter:
-    # Defines parameters for a CreateDisputeEvidenceFile request.
+    # Defines the parameters for a `CreateDisputeEvidenceFile` request.
     # @param [File | UploadIO] image_file Optional parameter: Example:
     # @return [CreateDisputeEvidenceFileResponse Hash] response from the API call
     def create_dispute_evidence_file(dispute_id:,
@@ -358,16 +357,15 @@ module Square
 
     # Submits evidence to the cardholder's bank.
     # Before submitting evidence, Square compiles all available evidence. This
-    # includes
-    # evidence uploaded using the
+    # includes evidence uploaded
+    # using the
     # [CreateDisputeEvidenceFile](https://developer.squareup.com/docs/reference/
     # square/disputes-api/create-dispute-evidence-file) and
     # [CreateDisputeEvidenceText](https://developer.squareup.com/docs/reference/
-    # square/disputes-api/create-dispute-evidence-text) endpoints,
-    # and evidence automatically provided by Square, when
-    # available.
-    # @param [String] dispute_id Required parameter: The ID of the dispute you
-    # want to submit evidence for.
+    # square/disputes-api/create-dispute-evidence-text) endpoints and
+    # evidence automatically provided by Square, when available.
+    # @param [String] dispute_id Required parameter: The ID of the dispute that
+    # you want to submit evidence for.
     # @return [SubmitEvidenceResponse Hash] response from the API call
     def submit_evidence(dispute_id:)
       # Prepare query url.

data/lib/square/api/inventory_api.rb

@@ -208,8 +208,8 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
     # results for the original query.  See the
-    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
-    # gination) guide for more information.
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion) guide for more information.
     # @return [RetrieveInventoryCountResponse Hash] response from the API call
     def retrieve_inventory_count(catalog_object_id:,
                                  location_ids: nil,

data/lib/square/api/invoices_api.rb

@@ -13,8 +13,8 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint.  Provide this cursor to retrieve the
     # next set of results for your original query.  For more information, see
-    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
-    # gination).
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion).
     # @param [Integer] limit Optional parameter: The maximum number of invoices
     # to return (200 is the maximum `limit`).  If not provided, the server  uses
     # a default limit of 100 invoices.
@@ -134,8 +134,8 @@ module Square
 
     # Deletes the specified invoice. When an invoice is deleted, the
     # associated Order status changes to CANCELED. You can only delete a draft
-    # invoice (you cannot delete an invoice scheduled for publication, or a
-    # published invoice).
+    # invoice (you cannot delete a published invoice, including one that is
+    # scheduled for processing).
     # @param [String] invoice_id Required parameter: The ID of the invoice to
     # delete.
     # @param [Integer] version Optional parameter: The version of the
@@ -214,12 +214,15 @@ module Square
       )
     end
 
-    # Updates an invoice by modifying field values, clearing field values, or
-    # both
-    # as specified in the request.
-    # There are no restrictions to updating an invoice in a draft state.
-    # However, there are guidelines for updating a published invoice.
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # Updates an invoice by modifying fields, clearing fields, or both. For most
+    # updates, you can use a sparse
+    # `Invoice` object to add fields or change values, and use the
+    # `fields_to_clear` field to specify fields to clear.
+    # However, some restrictions apply. For example, you cannot change the
+    # `order_id` or `location_id` field, and you
+    # must provide the complete `custom_fields` list to update a custom field.
+    # Published invoices have additional restrictions.
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # update.
     # @param [UpdateInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -261,8 +264,8 @@ module Square
 
     # Cancels an invoice. The seller cannot collect payments for
     # the canceled invoice.
-    # You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`,
-    # `CANCELED`, or `FAILED`.
+    # You cannot cancel an invoice in the `DRAFT` state or in a terminal state:
+    # `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
     # @param [String] invoice_id Required parameter: The ID of the
     # [invoice](#type-invoice) to cancel.
     # @param [CancelInvoiceRequest] body Required parameter: An object

data/lib/square/api/loyalty_api.rb

@@ -123,7 +123,7 @@ module Square
     # [CalculateLoyaltyPoints](#endpoint-Loyalty-CalculateLoyaltyPoints) to
     # compute the points. For more information,
     # see [Loyalty Program
-    # Overview](https://developer.squareup.com/docs/docs/loyalty/overview).
+    # 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.

data/lib/square/api/mobile_authorization_api.rb

@@ -16,8 +16,8 @@ module Square
     # ```
     # Replace `ACCESS_TOKEN` with a
     # [valid production authorization
-    # credential](https://developer.squareup.com/docs/docs/build-basics/access-t
-    # okens).
+    # credential](https://developer.squareup.com/docs/build-basics/access-tokens
+    # ).
     # @param [CreateMobileAuthorizationCodeRequest] 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/o_auth_api.rb

@@ -85,7 +85,7 @@ 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 [RevokeTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -126,9 +126,6 @@ module Square
     # The endpoint supports distinct methods of obtaining OAuth access tokens.
     # Applications specify a method by adding the `grant_type` parameter
     # in the request and also provide relevant information.
-    # For more information, see [OAuth access token
-    # management](https://developer.squareup.com/docs/authz/oauth/how-it-works#o
-    # auth-access-token-management).
     # __Note:__ Regardless of the method application specified,
     # the endpoint always returns two items; an OAuth access token and
     # a refresh token in the response.

data/lib/square/api/payments_api.rb

@@ -83,16 +83,14 @@ module Square
       )
     end
 
-    # Charges a payment source (for example, a card
-    # represented by customer's card on file or a card nonce). In addition
-    # to the payment source, the request must include the
-    # amount to accept for the payment.
-    # There are several optional parameters that you can include in the request
-    # (for example, tip money, whether to autocomplete the payment, or a
-    # reference ID
-    # to correlate this payment with another system).
-    # The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required
-    # to enable application fees.
+    # Creates a payment using the provided source. You can use this endpoint
+    # to charge a card (credit/debit card or
+    # 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).
+    # The endpoint creates a
+    # `Payment` object and returns it in the response.
     # @param [CreatePaymentRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -209,11 +207,53 @@ module Square
       )
     end
 
-    # Cancels (voids) a payment. If you set `autocomplete` to `false` when
-    # creating a payment,
-    # you can cancel the payment using this endpoint.
-    # @param [String] payment_id Required parameter: The `payment_id`
-    # identifying the payment to be canceled.
+    # Updates a payment with the APPROVED status.
+    # You can update the `amount_money` and `tip_money` using this endpoint.
+    # @param [String] payment_id Required parameter: The ID of the payment to
+    # update.
+    # @param [UpdatePaymentRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [UpdatePaymentResponse Hash] response from the API call
+    def update_payment(payment_id:,
+                       body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/payments/{payment_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'payment_id' => { 'value' => payment_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.put(
+        _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
+
+    # Cancels (voids) a payment. You can use this endpoint to cancel a payment
+    # with
+    # the APPROVED `status`.
+    # @param [String] payment_id Required parameter: The ID of the payment to
+    # cancel.
     # @return [CancelPaymentResponse Hash] response from the API call
     def cancel_payment(payment_id:)
       # Prepare query url.
@@ -249,9 +289,8 @@ module Square
     # Completes (captures) a payment.
     # By default, payments are set to complete immediately after they are
     # created.
-    # If you set `autocomplete` to `false` when creating a payment, you can
-    # complete (capture)
-    # the payment using this endpoint.
+    # You can use this endpoint to complete a payment with the APPROVED
+    # `status`.
     # @param [String] payment_id Required parameter: The unique ID identifying
     # the payment to be completed.
     # @return [CompletePaymentResponse Hash] response from the API call