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:



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/square/invoices/client.rb', line 204

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

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/invoices/#{params[:invoice_id]}/cancel",
    body: params.except(*_path_param_names)
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::CancelInvoiceResponse.load(_response.body)
  end

  raise _response.body
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:



42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/square/invoices/client.rb', line 42

def create(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/invoices",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::CreateInvoiceResponse.load(_response.body)
  end

  raise _response.body
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:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/square/invoices/client.rb', line 155

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
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::CreateInvoiceAttachmentResponse.load(_response.body)
  end

  raise _response.body
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:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/square/invoices/client.rb', line 126

def delete(request_options: {}, **params)
  _query_param_names = ["version"]
  _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::SANDBOX,
    method: "DELETE",
    path: "v2/invoices/#{params[:invoice_id]}",
    query: _query
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::DeleteInvoiceResponse.load(_response.body)
  end

  raise _response.body
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:



184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/square/invoices/client.rb', line 184

def delete_invoice_attachment(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "DELETE",
    path: "v2/invoices/#{params[:invoice_id]}/attachments/#{params[:attachment_id]}"
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::DeleteInvoiceAttachmentResponse.load(_response.body)
  end

  raise _response.body
end

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

Retrieves an invoice by invoice ID.

Returns:



84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/square/invoices/client.rb', line 84

def get(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "GET",
    path: "v2/invoices/#{params[:invoice_id]}"
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::GetInvoiceResponse.load(_response.body)
  end

  raise _response.body
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
 
# File 'lib/square/invoices/client.rb', line 16

def list(request_options: {}, **params)
  _query_param_names = %w[location_id cursor limit]
  _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::SANDBOX,
    method: "GET",
    path: "v2/invoices",
    query: _query
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::ListInvoicesResponse.load(_response.body)
  end

  raise _response.body
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:



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/square/invoices/client.rb', line 237

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

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/invoices/#{params[:invoice_id]}/publish",
    body: params.except(*_path_param_names)
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::PublishInvoiceResponse.load(_response.body)
  end

  raise _response.body
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:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/square/invoices/client.rb', line 66

def search(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/invoices/search",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::SearchInvoicesResponse.load(_response.body)
  end

  raise _response.body
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:



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

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

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "PUT",
    path: "v2/invoices/#{params[:invoice_id]}",
    body: params.except(*_path_param_names)
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::UpdateInvoiceResponse.load(_response.body)
  end

  raise _response.body
end