Class: Square::Orders::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/square/orders/client.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ void

Parameters:



9
10
11
 
# File 'lib/square/orders/client.rb', line 9

def initialize(client:)
  @client = client
end

Instance Method Details

#batch_get(request_options: {}, **params) ⇒ Square::Types::BatchGetOrdersResponse

Retrieves a set of [orders](entity:Order) by their IDs.

If a given order ID does not exist, the ID is ignored instead of generating an error.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/square/orders/client.rb', line 66

def batch_get(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders/batch-retrieve",
    body: Square::Orders::Types::BatchGetOrdersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::BatchGetOrdersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#calculate(request_options: {}, **params) ⇒ Square::Types::CalculateOrderResponse

Enables applications to preview order pricing without creating an order.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/square/orders/client.rb', line 100

def calculate(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders/calculate",
    body: Square::Orders::Types::CalculateOrderRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::CalculateOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#clone(request_options: {}, **params) ⇒ Square::Types::CloneOrderResponse

Creates a new order, in the ‘DRAFT` state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/square/orders/client.rb', line 135

def clone(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders/clone",
    body: Square::Orders::Types::CloneOrderRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::CloneOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#create(request_options: {}, **params) ⇒ Square::Types::CreateOrderResponse

Creates a new [order](entity:Order) that can include information about products for purchase and settings to apply to the purchase.

To pay for a created order, see [Pay for Orders](developer.squareup.com/docs/orders-api/pay-for-orders).

You can modify open orders using the [UpdateOrder](api-endpoint:Orders-UpdateOrder) endpoint.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/square/orders/client.rb', line 30

def create(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders",
    body: Square::Types::CreateOrderRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::CreateOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#custom_attribute_definitions ⇒ Square::CustomAttributeDefinitions::Client

Returns:

  • (Square::CustomAttributeDefinitions::Client) 


352
353
354
 
# File 'lib/square/orders/client.rb', line 352

def custom_attribute_definitions
  @custom_attribute_definitions ||= Square::Orders::CustomAttributeDefinitions::Client.new(client: @client)
end

#custom_attributes ⇒ Square::CustomAttributes::Client

Returns:

  • (Square::CustomAttributes::Client) 


357
358
359
 
# File 'lib/square/orders/client.rb', line 357

def custom_attributes
  @custom_attributes ||= Square::Orders::CustomAttributes::Client.new(client: @client)
end

#get(request_options: {}, **params) ⇒ Square::Types::GetOrderResponse

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

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :order_id (String)

Returns:



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/square/orders/client.rb', line 220

def get(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v2/orders/#{params[:order_id]}",
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::GetOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#pay(request_options: {}, **params) ⇒ Square::Types::PayOrderResponse

Pay for an [order](entity:Order) using one or more approved [payments](entity: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:

  • Reference the order by specifying the ‘order_id` when [creating the

payment](api-endpoint:Payments-CreatePayment). Any approved payments that reference the same ‘order_id` not specified in the `payment_ids` is canceled.

  • Be approved with [delayed

capture](developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture). Using a delayed capture payment with ‘PayOrder` completes the approved payment.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :order_id (String)

Returns:



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/square/orders/client.rb', line 324

def pay(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request_data = Square::Orders::Types::PayOrderRequest.new(params).to_h
  non_body_param_names = ["order_id"]
  body = request_data.except(*non_body_param_names)

  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders/#{params[:order_id]}/pay",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::PayOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#search(request_options: {}, **params) ⇒ Square::Types::SearchOrdersResponse

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 (such as Point of Sale, Invoices, and Connect APIs).

‘SearchOrders` requests need to specify which locations to search and define a [SearchOrdersQuery](entity:SearchOrdersQuery) object that controls how to sort or filter the results. Your `SearchOrdersQuery` can:

Set filter criteria.
Set the sort order.
Determine whether to return results as complete `Order` objects or as

[OrderEntry](entity:OrderEntry) objects.

Note that details for orders processed with Square Point of Sale while in 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.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/square/orders/client.rb', line 185

def search(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/orders/search",
    body: Square::Orders::Types::SearchOrdersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::SearchOrdersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#update(request_options: {}, **params) ⇒ Square::Types::UpdateOrderResponse

Updates an open [order](entity: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.

  • The latest ‘version` of the order to update.

  • The [sparse

order](developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects) containing only the fields to update and the version to which the update is being applied.

  • If deleting fields, the [dot notation

paths](developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete) identifying the fields to clear.

To pay for an order, see [Pay for Orders](developer.squareup.com/docs/orders-api/pay-for-orders).

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :order_id (String)

Returns:



270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/square/orders/client.rb', line 270

def update(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request_data = Square::Orders::Types::UpdateOrderRequest.new(params).to_h
  non_body_param_names = ["order_id"]
  body = request_data.except(*non_body_param_names)

  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v2/orders/#{params[:order_id]}",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::UpdateOrderResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end