charitable / vendor / square / square / src / Legacy / Apis / OrderCustomAttributesApi.php

OrderCustomAttributesApi.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at vendor/square/square/src/Legacy/Apis/OrderCustomAttributesApi.php

461 lines 21.3 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Square\Legacy\Apis;
6
7	use Core\Request\Parameters\BodyParam;
8	use Core\Request\Parameters\HeaderParam;
9	use Core\Request\Parameters\QueryParam;
10	use Core\Request\Parameters\TemplateParam;
11	use CoreInterfaces\Core\Request\RequestMethod;
12	use Square\Legacy\Http\ApiResponse;
13	use Square\Legacy\Models\BulkDeleteOrderCustomAttributesRequest;
14	use Square\Legacy\Models\BulkDeleteOrderCustomAttributesResponse;
15	use Square\Legacy\Models\BulkUpsertOrderCustomAttributesRequest;
16	use Square\Legacy\Models\BulkUpsertOrderCustomAttributesResponse;
17	use Square\Legacy\Models\CreateOrderCustomAttributeDefinitionRequest;
18	use Square\Legacy\Models\CreateOrderCustomAttributeDefinitionResponse;
19	use Square\Legacy\Models\DeleteOrderCustomAttributeDefinitionResponse;
20	use Square\Legacy\Models\DeleteOrderCustomAttributeResponse;
21	use Square\Legacy\Models\ListOrderCustomAttributeDefinitionsResponse;
22	use Square\Legacy\Models\ListOrderCustomAttributesResponse;
23	use Square\Legacy\Models\RetrieveOrderCustomAttributeDefinitionResponse;
24	use Square\Legacy\Models\RetrieveOrderCustomAttributeResponse;
25	use Square\Legacy\Models\UpdateOrderCustomAttributeDefinitionRequest;
26	use Square\Legacy\Models\UpdateOrderCustomAttributeDefinitionResponse;
27	use Square\Legacy\Models\UpsertOrderCustomAttributeRequest;
28	use Square\Legacy\Models\UpsertOrderCustomAttributeResponse;
29
30	class OrderCustomAttributesApi extends BaseApi
31	{
32	/**
33	* Lists the order-related [custom attribute definitions]($m/CustomAttributeDefinition) that belong to
34	* a Square seller account.
35	*
36	* When all response pages are retrieved, the results include all custom attribute definitions
37	* that are visible to the requesting application, including those that are created by other
38	* applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that
39	* seller-defined custom attributes (also known as custom fields) are always set to
40	* `VISIBILITY_READ_WRITE_VALUES`.
41	*
42	* @param string\|null $visibilityFilter Requests that all of the custom attributes be returned,
43	* or only those that are read-only or read-write.
44	* @param string\|null $cursor The cursor returned in the paged response from the previous call
45	* to this endpoint.
46	* Provide this cursor to retrieve the next page of results for your original request.
47	* For more information, see [Pagination](https://developer.squareup.com/docs/working-
48	* with-apis/pagination).
49	* @param int\|null $limit The maximum number of results to return in a single paged response.
50	* This limit is advisory.
51	* The response might contain more or fewer results. The minimum value is 1 and the
52	* maximum value is 100.
53	* The default value is 20.
54	* For more information, see [Pagination](https://developer.squareup.com/docs/working-
55	* with-apis/pagination).
56	*
57	* @return ApiResponse Response from the API call
58	*/
59	public function listOrderCustomAttributeDefinitions(
60	?string $visibilityFilter = null,
61	?string $cursor = null,
62	?int $limit = null
63	): ApiResponse {
64	$_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/orders/custom-attribute-definitions')
65	->auth('global')
66	->parameters(
67	QueryParam::init('visibility_filter', $visibilityFilter),
68	QueryParam::init('cursor', $cursor),
69	QueryParam::init('limit', $limit)
70	);
71
72	$_resHandler = $this->responseHandler()
73	->type(ListOrderCustomAttributeDefinitionsResponse::class)
74	->returnApiResponse();
75
76	return $this->execute($_reqBuilder, $_resHandler);
77	}
78
79	/**
80	* Creates an order-related custom attribute definition. Use this endpoint to
81	* define a custom attribute that can be associated with orders.
82	*
83	* After creating a custom attribute definition, you can set the custom attribute for orders
84	* in the Square seller account.
85	*
86	* @param CreateOrderCustomAttributeDefinitionRequest $body An object containing the fields to
87	* POST for the request.
88	*
89	* See the corresponding object definition for field details.
90	*
91	* @return ApiResponse Response from the API call
92	*/
93	public function createOrderCustomAttributeDefinition(
94	CreateOrderCustomAttributeDefinitionRequest $body
95	): ApiResponse {
96	$_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/v2/orders/custom-attribute-definitions')
97	->auth('global')
98	->parameters(HeaderParam::init('Content-Type', 'application/json'), BodyParam::init($body));
99
100	$_resHandler = $this->responseHandler()
101	->type(CreateOrderCustomAttributeDefinitionResponse::class)
102	->returnApiResponse();
103
104	return $this->execute($_reqBuilder, $_resHandler);
105	}
106
107	/**
108	* Deletes an order-related [custom attribute definition]($m/CustomAttributeDefinition) from a Square
109	* seller account.
110	*
111	* Only the definition owner can delete a custom attribute definition.
112	*
113	* @param string $key The key of the custom attribute definition to delete.
114	*
115	* @return ApiResponse Response from the API call
116	*/
117	public function deleteOrderCustomAttributeDefinition(string $key): ApiResponse
118	{
119	$_reqBuilder = $this->requestBuilder(
120	RequestMethod::DELETE,
121	'/v2/orders/custom-attribute-definitions/{key}'
122	)->auth('global')->parameters(TemplateParam::init('key', $key));
123
124	$_resHandler = $this->responseHandler()
125	->type(DeleteOrderCustomAttributeDefinitionResponse::class)
126	->returnApiResponse();
127
128	return $this->execute($_reqBuilder, $_resHandler);
129	}
130
131	/**
132	* Retrieves an order-related [custom attribute definition]($m/CustomAttributeDefinition) from a Square
133	* seller account.
134	*
135	* To retrieve a custom attribute definition created by another application, the `visibility`
136	* setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined
137	* custom attributes
138	* (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
139	*
140	* @param string $key The key of the custom attribute definition to retrieve.
141	* @param int\|null $version To enable [optimistic
142	* concurrency](https://developer.squareup.com/docs/build-basics/common-api-
143	* patterns/optimistic-concurrency)
144	* control, include this optional field and specify the current version of the custom
145	* attribute.
146	*
147	* @return ApiResponse Response from the API call
148	*/
149	public function retrieveOrderCustomAttributeDefinition(string $key, ?int $version = null): ApiResponse
150	{
151	$_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/orders/custom-attribute-definitions/{key}')
152	->auth('global')
153	->parameters(TemplateParam::init('key', $key), QueryParam::init('version', $version));
154
155	$_resHandler = $this->responseHandler()
156	->type(RetrieveOrderCustomAttributeDefinitionResponse::class)
157	->returnApiResponse();
158
159	return $this->execute($_reqBuilder, $_resHandler);
160	}
161
162	/**
163	* Updates an order-related custom attribute definition for a Square seller account.
164	*
165	* Only the definition owner can update a custom attribute definition. Note that sellers can view all
166	* custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.
167	*
168	* @param string $key The key of the custom attribute definition to update.
169	* @param UpdateOrderCustomAttributeDefinitionRequest $body An object containing the fields to
170	* POST for the request.
171	*
172	* See the corresponding object definition for field details.
173	*
174	* @return ApiResponse Response from the API call
175	*/
176	public function updateOrderCustomAttributeDefinition(
177	string $key,
178	UpdateOrderCustomAttributeDefinitionRequest $body
179	): ApiResponse {
180	$_reqBuilder = $this->requestBuilder(RequestMethod::PUT, '/v2/orders/custom-attribute-definitions/{key}')
181	->auth('global')
182	->parameters(
183	TemplateParam::init('key', $key),
184	HeaderParam::init('Content-Type', 'application/json'),
185	BodyParam::init($body)
186	);
187
188	$_resHandler = $this->responseHandler()
189	->type(UpdateOrderCustomAttributeDefinitionResponse::class)
190	->returnApiResponse();
191
192	return $this->execute($_reqBuilder, $_resHandler);
193	}
194
195	/**
196	* Deletes order [custom attributes]($m/CustomAttribute) as a bulk operation.
197	*
198	* Use this endpoint to delete one or more custom attributes from one or more orders.
199	* A custom attribute is based on a custom attribute definition in a Square seller account. (To create
200	* a
201	* custom attribute definition, use the
202	* [CreateOrderCustomAttributeDefinition]($e/OrderCustomAttributes/CreateOrderCustomAttributeDefinition
203	* ) endpoint.)
204	*
205	* This `BulkDeleteOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual delete
206	* requests and returns a map of individual delete responses. Each delete request has a unique ID
207	* and provides an order ID and custom attribute. Each delete response is returned with the ID
208	* of the corresponding request.
209	*
210	* To delete a custom attribute owned by another application, the `visibility` setting
211	* must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes
212	* (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
213	*
214	* @param BulkDeleteOrderCustomAttributesRequest $body An object containing the fields to POST
215	* for the request.
216	*
217	* See the corresponding object definition for field details.
218	*
219	* @return ApiResponse Response from the API call
220	*/
221	public function bulkDeleteOrderCustomAttributes(BulkDeleteOrderCustomAttributesRequest $body): ApiResponse
222	{
223	$_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/v2/orders/custom-attributes/bulk-delete')
224	->auth('global')
225	->parameters(HeaderParam::init('Content-Type', 'application/json'), BodyParam::init($body));
226
227	$_resHandler = $this->responseHandler()
228	->type(BulkDeleteOrderCustomAttributesResponse::class)
229	->returnApiResponse();
230
231	return $this->execute($_reqBuilder, $_resHandler);
232	}
233
234	/**
235	* Creates or updates order [custom attributes]($m/CustomAttribute) as a bulk operation.
236	*
237	* Use this endpoint to delete one or more custom attributes from one or more orders.
238	* A custom attribute is based on a custom attribute definition in a Square seller account. (To create
239	* a
240	* custom attribute definition, use the
241	* [CreateOrderCustomAttributeDefinition]($e/OrderCustomAttributes/CreateOrderCustomAttributeDefinition
242	* ) endpoint.)
243	*
244	* This `BulkUpsertOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert
245	* requests and returns a map of individual upsert responses. Each upsert request has a unique ID
246	* and provides an order ID and custom attribute. Each upsert response is returned with the ID
247	* of the corresponding request.
248	*
249	* To create or update a custom attribute owned by another application, the `visibility` setting
250	* must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes
251	* (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
252	*
253	* @param BulkUpsertOrderCustomAttributesRequest $body An object containing the fields to POST
254	* for the request.
255	*
256	* See the corresponding object definition for field details.
257	*
258	* @return ApiResponse Response from the API call
259	*/
260	public function bulkUpsertOrderCustomAttributes(BulkUpsertOrderCustomAttributesRequest $body): ApiResponse
261	{
262	$_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/v2/orders/custom-attributes/bulk-upsert')
263	->auth('global')
264	->parameters(HeaderParam::init('Content-Type', 'application/json'), BodyParam::init($body));
265
266	$_resHandler = $this->responseHandler()
267	->type(BulkUpsertOrderCustomAttributesResponse::class)
268	->returnApiResponse();
269
270	return $this->execute($_reqBuilder, $_resHandler);
271	}
272
273	/**
274	* Lists the [custom attributes]($m/CustomAttribute) associated with an order.
275	*
276	* You can use the `with_definitions` query parameter to also retrieve custom attribute definitions
277	* in the same call.
278	*
279	* When all response pages are retrieved, the results include all custom attributes that are
280	* visible to the requesting application, including those that are owned by other applications
281	* and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
282	*
283	* @param string $orderId The ID of the target [order](entity:Order).
284	* @param string\|null $visibilityFilter Requests that all of the custom attributes be returned,
285	* or only those that are read-only or read-write.
286	* @param string\|null $cursor The cursor returned in the paged response from the previous call
287	* to this endpoint.
288	* Provide this cursor to retrieve the next page of results for your original request.
289	* For more information, see [Pagination](https://developer.squareup.com/docs/working-
290	* with-apis/pagination).
291	* @param int\|null $limit The maximum number of results to return in a single paged response.
292	* This limit is advisory.
293	* The response might contain more or fewer results. The minimum value is 1 and the
294	* maximum value is 100.
295	* The default value is 20.
296	* For more information, see [Pagination](https://developer.squareup.com/docs/working-
297	* with-apis/pagination).
298	* @param bool\|null $withDefinitions Indicates whether to return the [custom attribute
299	* definition](entity:CustomAttributeDefinition) in the `definition` field of each
300	* custom attribute. Set this parameter to `true` to get the name and description of
301	* each custom attribute,
302	* information about the data type, or other definition details. The default value is
303	* `false`.
304	*
305	* @return ApiResponse Response from the API call
306	*/
307	public function listOrderCustomAttributes(
308	string $orderId,
309	?string $visibilityFilter = null,
310	?string $cursor = null,
311	?int $limit = null,
312	?bool $withDefinitions = false
313	): ApiResponse {
314	$_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/orders/{order_id}/custom-attributes')
315	->auth('global')
316	->parameters(
317	TemplateParam::init('order_id', $orderId),
318	QueryParam::init('visibility_filter', $visibilityFilter),
319	QueryParam::init('cursor', $cursor),
320	QueryParam::init('limit', $limit),
321	QueryParam::init('with_definitions', $withDefinitions)
322	);
323
324	$_resHandler = $this->responseHandler()->type(ListOrderCustomAttributesResponse::class)->returnApiResponse();
325
326	return $this->execute($_reqBuilder, $_resHandler);
327	}
328
329	/**
330	* Deletes a [custom attribute]($m/CustomAttribute) associated with a customer profile.
331	*
332	* To delete a custom attribute owned by another application, the `visibility` setting must be
333	* `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes
334	* (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
335	*
336	* @param string $orderId The ID of the target [order](entity:Order).
337	* @param string $customAttributeKey The key of the custom attribute to delete. This key must
338	* match the key of an
339	* existing custom attribute definition.
340	*
341	* @return ApiResponse Response from the API call
342	*/
343	public function deleteOrderCustomAttribute(string $orderId, string $customAttributeKey): ApiResponse
344	{
345	$_reqBuilder = $this->requestBuilder(
346	RequestMethod::DELETE,
347	'/v2/orders/{order_id}/custom-attributes/{custom_attribute_key}'
348	)
349	->auth('global')
350	->parameters(
351	TemplateParam::init('order_id', $orderId),
352	TemplateParam::init('custom_attribute_key', $customAttributeKey)
353	);
354
355	$_resHandler = $this->responseHandler()->type(DeleteOrderCustomAttributeResponse::class)->returnApiResponse();
356
357	return $this->execute($_reqBuilder, $_resHandler);
358	}
359
360	/**
361	* Retrieves a [custom attribute]($m/CustomAttribute) associated with an order.
362	*
363	* You can use the `with_definition` query parameter to also retrieve the custom attribute definition
364	* in the same call.
365	*
366	* To retrieve a custom attribute owned by another application, the `visibility` setting must be
367	* `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
368	* attributes
369	* also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
370	*
371	* @param string $orderId The ID of the target [order](entity:Order).
372	* @param string $customAttributeKey The key of the custom attribute to retrieve. This key must
373	* match the key of an
374	* existing custom attribute definition.
375	* @param int\|null $version To enable [optimistic
376	* concurrency](https://developer.squareup.com/docs/build-basics/common-api-
377	* patterns/optimistic-concurrency)
378	* control, include this optional field and specify the current version of the custom
379	* attribute.
380	* @param bool\|null $withDefinition Indicates whether to return the [custom attribute
381	* definition](entity:CustomAttributeDefinition) in the `definition` field of each
382	* custom attribute. Set this parameter to `true` to get the name and description of
383	* each custom attribute,
384	* information about the data type, or other definition details. The default value is
385	* `false`.
386	*
387	* @return ApiResponse Response from the API call
388	*/
389	public function retrieveOrderCustomAttribute(
390	string $orderId,
391	string $customAttributeKey,
392	?int $version = null,
393	?bool $withDefinition = false
394	): ApiResponse {
395	$_reqBuilder = $this->requestBuilder(
396	RequestMethod::GET,
397	'/v2/orders/{order_id}/custom-attributes/{custom_attribute_key}'
398	)
399	->auth('global')
400	->parameters(
401	TemplateParam::init('order_id', $orderId),
402	TemplateParam::init('custom_attribute_key', $customAttributeKey),
403	QueryParam::init('version', $version),
404	QueryParam::init('with_definition', $withDefinition)
405	);
406
407	$_resHandler = $this->responseHandler()
408	->type(RetrieveOrderCustomAttributeResponse::class)
409	->returnApiResponse();
410
411	return $this->execute($_reqBuilder, $_resHandler);
412	}
413
414	/**
415	* Creates or updates a [custom attribute]($m/CustomAttribute) for an order.
416	*
417	* Use this endpoint to set the value of a custom attribute for a specific order.
418	* A custom attribute is based on a custom attribute definition in a Square seller account. (To create
419	* a
420	* custom attribute definition, use the
421	* [CreateOrderCustomAttributeDefinition]($e/OrderCustomAttributes/CreateOrderCustomAttributeDefinition
422	* ) endpoint.)
423	*
424	* To create or update a custom attribute owned by another application, the `visibility` setting
425	* must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes
426	* (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.
427	*
428	* @param string $orderId The ID of the target [order](entity:Order).
429	* @param string $customAttributeKey The key of the custom attribute to create or update. This
430	* key must match the key
431	* of an existing custom attribute definition.
432	* @param UpsertOrderCustomAttributeRequest $body An object containing the fields to POST for
433	* the request.
434	*
435	* See the corresponding object definition for field details.
436	*
437	* @return ApiResponse Response from the API call
438	*/
439	public function upsertOrderCustomAttribute(
440	string $orderId,
441	string $customAttributeKey,
442	UpsertOrderCustomAttributeRequest $body
443	): ApiResponse {
444	$_reqBuilder = $this->requestBuilder(
445	RequestMethod::POST,
446	'/v2/orders/{order_id}/custom-attributes/{custom_attribute_key}'
447	)
448	->auth('global')
449	->parameters(
450	TemplateParam::init('order_id', $orderId),
451	TemplateParam::init('custom_attribute_key', $customAttributeKey),
452	HeaderParam::init('Content-Type', 'application/json'),
453	BodyParam::init($body)
454	);
455
456	$_resHandler = $this->responseHandler()->type(UpsertOrderCustomAttributeResponse::class)->returnApiResponse();
457
458	return $this->execute($_reqBuilder, $_resHandler);
459	}
460	}
461