square.rb 9.1.1.20210317 → 10.0.0.202104217

data/lib/square/api/invoices_api.rb

@@ -7,7 +7,7 @@ module Square
 
     # Returns a list of invoices for a given location. The response
     # is paginated. If truncated, the response includes a `cursor` that you
-    # use in a subsequent request to fetch the next set of invoices.
+    # use in a subsequent request to retrieve the next set of invoices.
     # @param [String] location_id Required parameter: The ID of the location for
     # which to list invoices.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
@@ -16,7 +16,7 @@ module Square
     # [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
+    # to return (200 is the maximum `limit`).  If not provided, the server uses
     # a default limit of 100 invoices.
     # @return [ListInvoicesResponse Hash] response from the API call
     def list_invoices(location_id:,
@@ -54,7 +54,7 @@ module Square
       )
     end
 
-    # Creates a draft [invoice](#type-invoice)
+    # Creates a draft [invoice]($m/Invoice)
     # for an order created using the Orders API.
     # A draft invoice remains in your account and no action is taken.
     # You must publish the invoice before Square can process it (send it to the
@@ -98,7 +98,7 @@ module Square
     # location and
     # optionally one customer.
     # The response is paginated. If truncated, the response includes a `cursor`
-    # that you use in a subsequent request to fetch the next set of invoices.
+    # that you use in a subsequent request to retrieve the next set of invoices.
     # @param [SearchInvoicesRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -133,15 +133,15 @@ module Square
     end
 
     # Deletes the specified invoice. When an invoice is deleted, the
-    # associated Order status changes to CANCELED. You can only delete a draft
+    # associated order status changes to CANCELED. You can only delete a draft
     # 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
-    # [invoice](#type-invoice) to delete. If you do not know the version, you
-    # can call [GetInvoice](#endpoint-Invoices-GetInvoice) or 
-    # [ListInvoices](#endpoint-Invoices-ListInvoices).
+    # [invoice]($m/Invoice) to delete. If you do not know the version, you can
+    # call [GetInvoice]($e/Invoices/GetInvoice) or 
+    # [ListInvoices]($e/Invoices/ListInvoices).
     # @return [DeleteInvoiceResponse Hash] response from the API call
     def delete_invoice(invoice_id:,
                        version: nil)
@@ -180,7 +180,7 @@ module Square
     end
 
     # Retrieves an invoice by invoice ID.
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # retrieve.
     # @return [GetInvoiceResponse Hash] response from the API call
     def get_invoice(invoice_id:)
@@ -216,10 +216,10 @@ module Square
 
     # 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
+    # `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
+    # `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
@@ -267,7 +267,7 @@ module Square
     # 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.
+    # [invoice]($m/Invoice) to cancel.
     # @param [CancelInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -318,8 +318,8 @@ module Square
     # `UNPAID` if
     # Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on
     # file for a portion of the
-    # invoice amount).
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # invoice amount.
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # publish.
     # @param [PublishInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding

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,9 @@ 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 either the `mapping` field (preferred) or the
+    # `mappings` field.
     # @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 +81,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 +122,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 +170,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 +219,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.
@@ -280,6 +283,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 +336,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 +421,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 +459,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 +499,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 +541,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/orders_api.rb

@@ -5,14 +5,15 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a new [Order](#type-order) which can include information on
-    # products for
+    # Creates a new [Order]($m/Order) which can include information on products
+    # for
     # purchase and settings to apply to the purchase.
-    # To pay for a created order, please refer to the [Pay for
+    # 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.
+    # 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,7 +47,7 @@ module Square
       )
     end
 
-    # Retrieves a set of [Order](#type-order)s by their IDs.
+    # 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
     # generating an error.
     # @param [BatchRetrieveOrdersRequest] body Required parameter: An object
@@ -82,7 +83,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.
@@ -121,12 +122,12 @@ module 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
+    # [`SearchOrdersQuery`]($m/SearchOrdersQuery) object which 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.
+    # [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
     # orders have a `created_at` value that reflects the time the order was
@@ -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,7 +201,7 @@ 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:
     # - The `order_id` in the endpoint path, identifying the order to update.
@@ -214,7 +215,8 @@ module Square
     # 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
+    # To pay for an order, please refer to the
+    # [Pay for
     # Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
     # guide.
     # @param [String] order_id Required parameter: The ID of the order to
@@ -257,8 +259,8 @@ 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
@@ -267,7 +269,7 @@ module Square
     # array of `payment_ids` in the request.
     # 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.

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/subscriptions_api.rb

@@ -220,7 +220,7 @@ module Square
     # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
     # ion).
     # @param [Integer] limit Optional parameter: The upper limit on the number
-    # of subscription events to return  in the response.   Default: `200`
+    # of subscription events to return in the response.  Default: `200`
     # @return [ListSubscriptionEventsResponse Hash] response from the API call
     def list_subscription_events(subscription_id:,
                                  cursor: nil,
@@ -259,5 +259,40 @@ module Square
         _response, data: decoded, errors: _errors
       )
     end
+
+    # Resumes a deactivated subscription.
+    # @param [String] subscription_id Required parameter: The ID of the
+    # subscription to resume.
+    # @return [ResumeSubscriptionResponse Hash] response from the API call
+    def resume_subscription(subscription_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/subscriptions/{subscription_id}/resume'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'subscription_id' => { 'value' => subscription_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _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