Class: Square::Invoices::Client

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

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Square::Invoices::Client 



7
8
9
 
# File 'lib/square/invoices/client.rb', line 7

def initialize(client:)
  @client = client
end

Instance Method Details

#cancel(request_options: {}, **params) ⇒ Square::Types::CancelInvoiceResponse

Cancels an invoice. The seller cannot collect payments for the canceled invoice.

You cannot cancel an invoice in the ‘DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.

Returns:



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/square/invoices/client.rb', line 258

def cancel(request_options: {}, **params)
  _path_param_names = ["invoice_id"]

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/invoices/#{params[:invoice_id]}/cancel",
    body: params.except(*_path_param_names)
  )
  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::CancelInvoiceResponse.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::CreateInvoiceResponse

Creates a draft [invoice](entity: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 customer’s email address or charge the customer’s card on file).

Returns:



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/square/invoices/client.rb', line 51

def create(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/invoices",
    body: params
  )
  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::CreateInvoiceResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

#create_invoice_attachment(request_options: {}, **params) ⇒ Square::Types::CreateInvoiceAttachmentResponse

Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON ‘request` part and a `file` part. The `file` part must be a `readable stream` that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF.

Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the ‘DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

NOTE: When testing in the Sandbox environment, the total file size is limited to 1 KB.

Returns:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/square/invoices/client.rb', line 197

def create_invoice_attachment(request_options: {}, **params)
  body = Internal::Multipart::FormData.new

  if params[:request]
    body.add(
      name: "request",
      value: params[:request],
      content_type: "application/json; charset=utf-8"
    )
  end
  body.add_part(params[:image_file].to_form_data_part(name: "image_file")) if params[:image_file]

  _request = Square::Internal::Multipart::Request.new(
    method: POST,
    path: "v2/invoices/#{params[:invoice_id]}/attachments",
    body: body
  )
  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::CreateInvoiceAttachmentResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

#delete(request_options: {}, **params) ⇒ Square::Types::DeleteInvoiceResponse

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 a published invoice, including one that is scheduled for processing).

Returns:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/square/invoices/client.rb', line 159

def delete(request_options: {}, **params)
  _query_param_names = [
    ["version"],
    %i[version]
  ].flatten
  _query = params.slice(*_query_param_names)
  params = params.except(*_query_param_names)

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "DELETE",
    path: "v2/invoices/#{params[:invoice_id]}",
    query: _query
  )
  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::DeleteInvoiceResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

#delete_invoice_attachment(request_options: {}, **params) ⇒ Square::Types::DeleteInvoiceAttachmentResponse

Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the ‘DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

Returns:



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/square/invoices/client.rb', line 232

def delete_invoice_attachment(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "DELETE",
    path: "v2/invoices/#{params[:invoice_id]}/attachments/#{params[:attachment_id]}"
  )
  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::DeleteInvoiceAttachmentResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

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

Retrieves an invoice by invoice ID.

Returns:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/square/invoices/client.rb', line 105

def get(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "GET",
    path: "v2/invoices/#{params[:invoice_id]}"
  )
  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::GetInvoiceResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

#list(request_options: {}, **params) ⇒ Square::Types::ListInvoicesResponse

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 retrieve the next set of invoices.

Returns:



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/square/invoices/client.rb', line 16

def list(request_options: {}, **params)
  _query_param_names = [
    %w[location_id cursor limit],
    %i[location_id cursor limit]
  ].flatten
  _query = params.slice(*_query_param_names)
  params.except(*_query_param_names)

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "GET",
    path: "v2/invoices",
    query: _query
  )
  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::ListInvoicesResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end

#publish(request_options: {}, **params) ⇒ Square::Types::PublishInvoiceResponse

Publishes the specified draft invoice.

After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer’s email address, charges the customer’s card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page.

The invoice ‘status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if Square emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the invoice amount.

In addition to the required ‘ORDERS_WRITE` and `INVOICES_WRITE` permissions, `CUSTOMERS_READ` and `PAYMENTS_WRITE` are required when publishing invoices configured for card-on-file payments.

Returns:



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/square/invoices/client.rb', line 297

def publish(request_options: {}, **params)
  _path_param_names = ["invoice_id"]

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/invoices/#{params[:invoice_id]}/publish",
    body: params.except(*_path_param_names)
  )
  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::PublishInvoiceResponse.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::SearchInvoicesResponse

Searches for invoices from a location specified in the filter. You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer.

The response is paginated. If truncated, the response includes a ‘cursor` that you use in a subsequent request to retrieve the next set of invoices.

Returns:



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/square/invoices/client.rb', line 81

def search(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/invoices/search",
    body: params
  )
  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::SearchInvoicesResponse.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::UpdateInvoiceResponse

Updates an invoice. This endpoint supports sparse updates, so you only need to specify the fields you want to change along with the required ‘version` field. Some restrictions apply to updating invoices. For example, you cannot change the `order_id` or `location_id` field.

Returns:



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/square/invoices/client.rb', line 131

def update(request_options: {}, **params)
  _path_param_names = ["invoice_id"]

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "PUT",
    path: "v2/invoices/#{params[:invoice_id]}",
    body: params.except(*_path_param_names)
  )
  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::UpdateInvoiceResponse.load(_response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(_response.body, code: code)
  end
end