Class: Square::TransferOrders::Client

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

Instance Method Summary collapse

Constructor Details

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



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

def initialize(client:)
  @client = client
end

Instance Method Details

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

Cancels a transfer order in STARTED or PARTIALLY_RECEIVED status. Any unreceived quantities will no longer be receivable and will be immediately returned to the source Location's inventory.

Common reasons for cancellation:

  • Items no longer needed at destination
  • Source location needs the inventory
  • Order created in error

Creates a transfer_order.updated webhook event.

Returns:



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/square/transfer_orders/client.rb', line 199

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

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/transfer-orders/#{params[:transfer_order_id]}/cancel",
    body: params.except(*_path_param_names),
    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::CancelTransferOrderResponse.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::CreateTransferOrderResponse

Creates a new transfer order in DRAFT status. A transfer order represents the intent to move CatalogItemVariations from one Location to another. The source and destination locations must be different and must belong to your Square account.

In DRAFT status, you can:

  • Add or remove items
  • Modify quantities
  • Update shipping information
  • Delete the entire order via DeleteTransferOrder

The request requires source_location_id and destination_location_id. Inventory levels are not affected until the order is started via StartTransferOrder.

Common integration points:

  • Sync with warehouse management systems
  • Automate regular stock transfers
  • Initialize transfers from inventory optimization systems

Creates a transfer_order.created webhook event.

Returns:



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

def create(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/transfer-orders",
    body: params,
    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::CreateTransferOrderResponse.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::DeleteTransferOrderResponse

Deletes a transfer order in DRAFT status. Only draft orders can be deleted. Once an order is started via StartTransferOrder, it can no longer be deleted.

Creates a transfer_order.deleted webhook event.

Returns:



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/transfer_orders/client.rb', line 160

def delete(request_options: {}, **params)
  params = Square::Internal::Types::Utils.symbolize_keys(params)
  _query_param_names = %i[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],
    method: "DELETE",
    path: "v2/transfer-orders/#{params[:transfer_order_id]}",
    query: _query,
    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::DeleteTransferOrderResponse.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::RetrieveTransferOrderResponse

Retrieves a specific TransferOrder by ID. Returns the complete order details including:

  • Basic information (status, dates, notes)
  • Line items with ordered and received quantities
  • Source and destination Locations
  • Tracking information (if available)

Returns:



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

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

#receive(request_options: {}, **params) ⇒ Square::Types::ReceiveTransferOrderResponse

Records receipt of CatalogItemVariations for a transfer order. This endpoint supports partial receiving - you can receive items in multiple batches.

For each line item, you can specify:

  • Quantity received in good condition (added to destination inventory with InventoryState of IN_STOCK)
  • Quantity damaged during transit/handling (added to destination inventory with InventoryState of WASTE)
  • Quantity canceled (returned to source location's inventory)

The order must be in STARTED or PARTIALLY_RECEIVED status. Received quantities are added to the destination Location's inventory according to their condition. Canceled quantities are immediately returned to the source Location's inventory.

When all items are either received, damaged, or canceled, the order moves to COMPLETED status.

Creates a transfer_order.updated webhook event.

Returns:



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/square/transfer_orders/client.rb', line 241

def receive(request_options: {}, **params)
  _path_param_names = ["transfer_order_id"]

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/transfer-orders/#{params[:transfer_order_id]}/receive",
    body: params.except(*_path_param_names),
    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::ReceiveTransferOrderResponse.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::SearchTransferOrdersResponse

Searches for transfer orders using filters. Returns a paginated list of matching TransferOrders sorted by creation date.

Common search scenarios:

Returns:



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

def search(request_options: {}, **params)
  Square::Internal::CursorItemIterator.new(
    cursor_field: :cursor,
    item_field: :transfer_orders,
    initial_cursor: params[:cursor]
  ) do |next_cursor|
    params[:cursor] = next_cursor
    _request = Square::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "POST",
      path: "v2/transfer-orders/search",
      body: params,
      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::SearchTransferOrdersResponse.load(_response.body)
    else
      error_class = Square::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(_response.body, code: code)
    end
  end
end

#start(request_options: {}, **params) ⇒ Square::Types::StartTransferOrderResponse

Changes a DRAFT transfer order to STARTED status. This decrements inventory at the source Location and marks it as in-transit.

The order must be in DRAFT status and have all required fields populated. Once started, the order can no longer be deleted, but it can be canceled via CancelTransferOrder.

Creates a transfer_order.updated webhook event.

Returns:



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/square/transfer_orders/client.rb', line 275

def start(request_options: {}, **params)
  _path_param_names = ["transfer_order_id"]

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/transfer-orders/#{params[:transfer_order_id]}/start",
    body: params.except(*_path_param_names),
    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::StartTransferOrderResponse.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::UpdateTransferOrderResponse

Updates an existing transfer order. This endpoint supports sparse updates, allowing you to modify specific fields without affecting others.

Creates a transfer_order.updated webhook event.

Returns:



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

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

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